o 






GC26-4056-1 
File No. S370-30 



MVS/370 

System Programming Library; 
Program Product Data l\/lanagement 



Data Facility Product 5665-295 
Release 1.1 



c 



Second Edition (October 1983) ^r -, 

This is a major revision of, and makes obsolete, GC26-4056-0. x.y 

This edition, applies to Release 1.1 of MVS/370 Data Facility 
Product, Program Product 5665-295, and to any subsequent 
releases until otherwise indicated in neM editions or technical 
newsletters. 

The changes for this edition are summarized under "Summary of 
Amendments" following the preface. Specific changes are 
indicated by a vertical bar to the left of the change. These 
bars will be deleted at any subsequent replication of the page 
affected. Editorial changes that have no technical significance 
are not noted. 

Changes are periodically made to the information herein; before 
using this publication in connection with the operation of IBN 
systems, consult the latest IBM Svstem/370 and 4300 Processors 
Bibliography , GC20-0001, for the editions that are applicable 
and current. 

References in this publication to IBM products, programs, or 
services do not imply that IBM intends to make these available 
in all countries in which IBM operates. Any reference to an IBM 
program product in this publication is not intended to state or 
imply that only IBM's program product may be used. Any 
functionally equivalent program may be used instead. 

Publications are not stocked at the address given below; 
requests for IBM publications should be made to your IBM 
representative or to the IBM branch office serving your 
locality. 

A form for readers* comments is provided at the back of this 
publication. If the form has been removed, comments may be 
addressed to IBM Corporation, P.O. Box 50020, Programming 
Publishing, San Jose, California, U.S.A. 95150. IBM may use or 
distribute whatever information you supply in any way it 
believes appropriate without incurring any obligation to you. 

© Copyright International Business Machines Corporation 1983 



PREFACE 









ORGANIZATION 



This publication provides information for system programmers 
about MVS/370 Data Facility Product» and how to modify and 
extend the data management capabilities of the operating system. 



This publication contains 11 chapters and 5 appendixes^ 

• "Chapter 1. Using Catalog Management Macro Instructions^" 
contains information on the macro instructions used for 
retrieving catalog information from OS CVOLSf and for 
adding^ deleting^ and updating catalog entries for non-VSAM 
data sets. 

• "Chapter 2. Maintaining the Volume Table of Contents 
(VTOC)," describes the structure of the VTOC and VTOC index* 
and discusses houi to use system macros to read a data set 
control block* rename a data set* or delete a data set from 
the VTOC. 

• "Chapter 3. Executing Your Own Channel Programs (EXCP)," 
describes how to use the EXCP macro to control device 
characteristics and data organization with your own channel 
programs. 

• "Chapter 4. Using XDAP to Read and Urite to Direct Access 
Devices*" describes how to use the XDAP macro to read* 
verify* and update blocks without using an access method. 

• "Chapter 5. Password Protecting Your Data Sets*" contains 
information on system password protection and how to create 
and maintain the PASSWORD data set. 

• "Chapter 6. Exit Routines*" describes some of the 
IBM-supplied exits for installation-written routines and 
authorized user programs. 

• "Chapter 7. System Macro Instructions*" contains the system 
macros used to refer to* validate* and modify system data 
areas. 

• "Chapter 8. Maintaining SYSl . IMAGELIB*" describes how to add 
a UCS or FCB image to the system image library* and how to 
maintain the UCS image tables. 

• "Chapter 9. JES2 Support for the IBM 1403* 3203 Model 5* and 
3211 Printers*" describes the JES2 support for UCS alias 
names and the 3211 indexing feature. 

• "Chapter 10. CATALOG* SCRATCH* and RENAME Dummy Modules," 
contains a description of the dummy modules for CATALOG* 
SCRATCH* and RENAME* and how to replace them. 

• "Chapter 11. Specifying Buffer Numbers for DASD Data Sets*" 
contains performance considerations for using the BUFNO 
keyword of the DCB macro to allocate BSAM buffers. 

• "Appendix A. VTOC Access Macros," contains the format and 
description of the four VTOC access macros: CVAFDIR* 
CVAFDSM* CVAFSEQ* and CVAFTST. 

• "Appendix B. Examples of VTOC Access Macros*" contains 
examples of how to use the VTOC access macros in your 
programs. 

• "Appendix C. Return Codes from VTOC Access Macros," contains 
the return codes generated by the four VTOC access macros. 
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• "Appendix D. VTOC Error Messages and Associated Codes*** 
contains the error messages and field codes issued by the 
Common VTOC Access Facility (CVAF). 

• **Appendix E. Example of an Open Exit Module*** contains a 
program listing for IFGOEXOB* an installation-written exit 
routine that takes control during OPEN for a DCB. 

The operating system provides simpler Mays (for example* access 
method services* job control language* utility programs* access 
method routines) to perform most of the tasks discussed in this 
book. The information presented here is intended to provide 
greater flexibility in using the data management capabilities. 






PREREQUISITE KN0I4LED6E 



In order to use this book efficiently* you should be familiar 
Mith the following topics! 

Assembler language 

Standard program linkage conventions 

Catalog management for OS CVOLs 

The utility programs lEHLIST, lEHMOVE* and lEHPROGM 

Data management access methods and macro instructions 



REQUIRED PUBLICATIONS 



You should be familiar with the information presented in the 
following publications: 

• O5/VS-D0S/VSE-VM/370 Assembler Language contains more 
information on coding in assembler language. 

• 0S/VS2 Supervisor Services and Macro Instructions contains a 
description of standard linkage conventions. 

• MVS/370 Access Method Services Reference for the Integrated 
Catalog Facility or MVS/370 Access Method Services Reference 
for VSAM Catalogs describes how to maintain catalogs. 

• MVS/370 Utilities describes how to use lEHLIST to maintain 
the VTOC* IEHMOVE to maintain OS CVOLs* and lEHPROGM to 
protect data sets. 

• MVS/370 Data Management Services and MVS/370 Data Management 
Macro Instructions contain information on using access 
methods and macro instructions to do input and output. 

More specific prerequisite reading is listed at the beginning of 
some chapters* as it relates to the particular topic. 
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RELATED PUBLICATIONS 



Uithin the text* references are made to the publications listed 
in the table below. 



Short Title 


Publication Title 


Order Number 


Access Method 
Services Reference 


MVS/370 Access Method 
Services Reference for 
the Integrated Catalog 
Faci li tv 


GC26-4051 
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Short Title 


Publication Title 


Order Number 


Access MQthod 
Services Reference 


MVS/370 Access Methpd 
Services Reference for 
VSAM Cataloas 


GC26-4059 


Catalog Users Guide 


MVS/370 Cataloc, Users 
Guide 


GC26-<J053 


Checkpoi nt/Restart 


MVS/370 

Checkpo i nt/Restart 


GC26-^05<i 


CVAF Diagnosis 
Reference 


MVS/370 Common VTOC 
Access Facility 
Diaqnosis Reference 


SY26-3933 


DADSM and CVAF 
Diagnosis Guide 


MVS/370 DADSM and Common 
VTOC Access Facilitv 
Diaanosis Guide 


SY26-3918 


DADSM Diagnosis 
Reference 


MVS/370 DADSM Diaanosis 
Reference 


SY26-3919 


Data Facility 
Product J General 
Information 


nVS/370 Data Facility 
Product: General 
Informati on 


GC26-^050 


Data Management 
Macro Instructions 


MVS/370 Data Management 
llacro Instruct ion? 


GC26-<»057 


Data Management 
Services 


MVS/370 Data Management 
Services 


GC26-4058 


Debugging Handbook 


0S/VS2 MVS Svstem 
Proaramming Library? 
Debugciina Handbook* 
Volumes 1-3 


GC28-1047 
GC28-1048 
GC28-10<t9 


Device Support 
Facilities User's 
Guide and Reference 


Device Support 
Facilities User's Guide 
^nd Reference 


GC35-0033 


IBM System/370 
Principles of 
Operation 


IBM Svstem/370 
Principles of Op^r^tipn 


GA22-7000 


IBM 2821 Control 
Unit Component 
Description 


IBM 28?1 Contrpl Unit 
Component Description 


GA24-3312 


IBM 3203 Printer 
Component 
Description and 
Operator's Guide 


IBM 3203 Printer 
Component Description 
and Operator's Guide 


GA33-1515 
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Short Title 


Publication Title 


Order Number 


IBM 3211 Printer, 
3216 Interchangeable 
Train Cartridge, and 
3811 Printer Control 
Unit Component 
Description and 
Operator's Guide 


IBM 3211 Printer, 3216 
Interchangeable Train 
Cartridge, and 3811 
Printer Control Unit 
Component Description 
and Operator's Guide 


GA24-3543 1 


IBM 3800 Printing 
Subsystem 
Programmer's Guide 


IBM 3800 Printina 
Subsystem Proorammer's 
Gui de 


GC26-3846 


IBM ^2<i5 Printer 
Model 1 Component 
Description and 
Operator's Guide 


IBM 4245 Printer Model 1 
Component Description 
and Operator's Guide 


GA33-1541 


JCL 


0S/VS2 MVS JCL 


GC28-0692 


Linkage Editor and 
Loader 


MVS/370 Linkaae Editor 
and Loader 


GC26-4061 


Magnetic Tape Labels 
and File Structure 


MVS/370 Magnetic Tape 
Labels and File 
Structure 


GC26-4064 


Message Library* 
System Messages 


OS/VS Message Library: 
VS2 System Messages 


GC28-1002 


Network Job Entry 
Facility for JES2 


0S/VS2 MVS Svstem 
Programming Library: 
Network Job Entry 
Facility for JES2 


SC23-0003 \ 


OS/VS-DOS/VSE-VM/370 
Assembler Language 


OS/VS-DOS/VSE-VM/370 
Assembler Language 


GC33-4010 


0S/VS2 I/O 
Supervisor Logic 


0S/VS2 I/O Supervisor 
Loaic 


SY26-3823 


Open/Close/EOV Logic 


MVS/370 Open/Close/EOV 
Logi c 


LY26-3924 


RACF General 
Information Manual 


Resource Access Control 
Facility (RACF): General 
Information Manual 


GC28-0722 


Supervisor Services 
and Macro 
Instructions 


0S/VS2 MVS Supervisor 
Services and Macro 
Instructi ons 


GC28-0683 


System Generation 
Reference 


MVS/370 Svstem 
Generation Reference 


GC26-4063 
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Short Title 


Publication Title 


Order Number 


System Programming 
Library? 

Initialization and 
Tuning Guide 


0S/VS2 MVS Svstem 
Proqramming Library: 
Initialization and 
Tuninq Guide 


GC28-0681 


System Programming 
Library: JES2 


0S/VS2 MVS Svstem 
Programming Library: 
JES2 


GC23-0002 


System Programming 
Library: JES3 


0S/VS2 MVS Svstem 
Programming Library: 
JES3 


GC28-0608 


System Programming 
Library: Service 
Aids 


0S/VS2 MVS Svstem 
Proqramming Library: 
Service Aids 


GC28-0674 


System Programming 
Library: Supervisor 


0S/VS2 MVS Svstem 
Proqramming Library: 
Supervisor 


GC28-0628 


TSO Command Language 
Reference 


0S/VS2 TSO Command 
Lanquaqe Reference 


GC28-0646 


Utilities 


MVS/370 Utilities 


GC26-4065 


VSAM Reference 


MVS/370 VSAM Reference 


GC26-4074 



NOTATIONAL CONVENTIONS 
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A uniform system of notation describes the format of data 
management macro instructions. This notation is not part of the 
language; it simply provides a basis for describing the 
structure of the commands. 

The command format illustrations in this book use the follouiing 
conventi ons: 

• Brackets [ ] indicate an optional parameter. 

• Braces i } indicate a choice of entry; unless a default is 
indicated* you must choose one of the entries. 

Items separated by a vertical bar (|) represent alternative 
items. No more than one of these items may be selected. 

• An ellipsis (...) indicates that multiple entries of the 
type immediately preceding the ellipsis are allowed. 

• Other punctuation (parentheses, commas, spaces, etc.) must 
be entered as shouin. A space is indicated by a blank. 

• BOLDFACE type indicates the exact characters to be entered, 
except as described in the bulleted notes above. Such items 
must be entered exactly as illustrated. 

• Lowercase underscored type specifies fields to be supplied 
by the user. 

• BOLDFACE UNDERSCORED type indicates a default option. If 
the parameter is omitted, the underscored value is assumed. 
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Parentheses ( ) must enclose subfields if more than one Is 
specified. If only one subfield is specified* you may omit 
the parentheses. 
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ADDRESS AND REGISTER CONVENTIONS 



CD 



The folloMing describes the meaning of each notation used to 
shoM hoM an operand can be coded: 

symbol 

Uhen this notation is shoMn» the operand can be any valid 
assembler-language symbol. 

Uhen this notation is shoMn» general register £ can be used 
as an operand. Uhen used as an operand in a macro 
instruction* the register must be specified as the decimal 
digit 0. enclosed in parentheses as shoMn above. 

Uhen this notation is shown* general register JL can be used 
as an operand. Uhen used as an operand in a macro 
instruction* the register must be specified as the decimal 
digit JL enclosed in parentheses .as shoMn above. Uhen 
register i is used* the instruction loaded into the 
register is not included in the macro expansion. 

( 2-12 ) 

Uhen this notation is shown* the operand specified can be 
any of the general registers £ through JL^. All registers 
as operands must be coded in parentheses* for example* if 
register 3 is coded* it is coded as (3). Uhen one of the 
registers £ through jL2 is used* it can be coded as a 
decimal digit* symbol (equated to a decimal digit)* or an 
expression that results in a value of 2 through 12. 

RX~Tvpe Address 

Uhen this notation is shoMn* the operand can be specified 
as any valid assembler-language RX-type address. The 
following shows examples of each valid RX-type address^ 
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Name 

ALPHAl 

ALPHA2 

BETAl 

BETA2 

GAMMA 1 

GAMMA2 

GAMMA3 

LAMBDAl 



Operation Operand 



1*39(4*10) 

REG1*39(4,TEN) 

2*ZETA(4) 

REG2*ZETA(REG4) 

2,ZETA 

REG2*ZETA 

2*=F»1000' 

3*20(*5) 



Both ALPHA instructions specify explicit addresses* REGl 
and TEN have been defined as absolute symbols. Both BETA 
instructions specify implied addresses* and both use index 
registers. Indexing is omitted from the GAMMA 
instructions. 6AMMA1 and GAMMA2 specify implied addresses. 
The second operand of GAMMA3 is a literal. LAMBDAl 
specifies an explicit address with no indexing. 

A-Tvpe Address 

Uhen this notation is shown* the operand can be specified 
as any address that can be written as a valid 
assembler-language A-type address constant. An A-type 
address constant can be written as an absolute value* a 
relocatable symbol* or a relocatable expression. Operands 
that require an A-type address are inserted into an A-type 
address constant during the macro expansion process. For 
more details about A-type address constants* refer to 
OS/VS-DOS/VSE--VM/370 Assembler Language . 
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absexp 

Mhen this notation is shoun» the operand can be an absolute 
value or expression. An absolute expression can be an 
absolute term or an arithmetic combination of absolute 
terms. An absolute term can be a nonrelocatable symbols a 
self-defining term» or the length attribute reference. For 
more details about absolute expressions* refer to 
OS/VS-DOS/VSE-VM/370 Assembler Language . 

relexp 

Uhen this notation is shoMn» the operand can be a 
relocatable symbol or expression. A relocatable symbol or 
expression is one whose value changes by n if the program 
in Mhich it appears is relocated n bytes away from its 
originally assigned &rea of storage. For more details 
about relocatable symbols and expressions* refer to 
OS/VS-DOS/VSE~VM/370 Assembler Language . 



Preface ix 



SUMMARY OF AMENDHENTS 



RELEASE 1.1, OCTOBER 1983 



NEH DEVICE SUPPORT 



SERVICE CHANGES 



Information to support the folloMing new device has been added 
to Figure 34 on page 142: 

• 4245 Printer 

The chapter, "Maintaining SYSl. IMAGELIB»" has been added. This 
chapter replaces the section formerly titled* "Adding a UCS 
Image or FCB Image to the System Image Library." The neM 
chapter contains the information previously found in the old 
chapter, plus a description of the UCS image table, and 
procedures for updating the image table for the 4245 printer. 



Chapter 2, formerly titled "Controlling Space on DASD Volumes," 
has been renamed, "Managing the Volume Table of Contents 
(VTOC)." 

Minor service changes have also been made throughout the manual 
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CHAPTER 1. USING CATALOG MANAGEMENT HACRO INSTRUCTIONS 






Using catalog management macro instructions* you can do the 
following things: 

• Retrieve information from an ICF catalog* a VSAM catalog* or 
an OS CVOL 

• Catalog non-VSAM data sets in an ICF catalog* a VSAM 
catalog* or an OS CVOL 

• Uncatalog non-VSAM data sets from an ICF catalog* a VSAM 
catalog* or an OS CVOL 

• Recatalog non-VSAM data sets in an ICF catalog* a VSAM 
catalog* or an OS CVOL 

• Read a block from an OS CVOL 

• Build an index in an OS CVOL 

• Build a generation index in an OS CVOL 

• Delete an index from an OS CVOL 

• Assign an alias to a high-level index in an OS CVOL 

• Delete an index alias from an OS CVOL 

• Connect two OS CVOLs 

• Disconnect two OS CVOLs 

Before using the information in this chapter* you should be 
familiar with the following publications: 

• OS/VS--DOS/VSE-VM/370 Assembler Language contains information 
you will need to code programs in the assembler language. 

• Access Method Services Reference tells how to use programs 
that offer some of the same services as OS CVOL management 
macros plus additional services that the macros cannot 
provide. 

• ^CL tells how to catalog and uncatalog non-VSAM data sets 
using job control language statements. 

• Catalog Users Guide tells how to use OS CVOLs. 

Specifications for coding the macro instructions are presented 
with each function to be performed. Accompanying the 
descriptions are coding examples and programming notes* 
exception return codes follow the coding examples. In the 
functional descriptions* offsets into data areas are numbered 
from zero (the first byte is byte zero). 
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CATALOG ORDER OF SEARCH 



The order in Mhich catalogs are searched Mhen an entry is to be Tf) 
located is? ^A_^ 

1. If a specific catalog is specified in a macro* only that 
catalog is searched. If the entry is not found* a "no entry 
found" error is returned to the user. 

2. Any user catalog(s) specified in the current job step with a 
STEPCAT DD statement is searched. If more than one catalog 
is specified for the job step* the catalogs are searched in 
order of concatenation. If the entry is found* no other 
catalog is searched. 

If a STEPCAT catalog is specified and the entry is not 
found* the JOBCAT catalog is not searched. The catalog 
search continues Mith step 3 beloM. 

If no STEPCAT catalog is specified for the job step* and a 
user catalog is specified for the current job with a JOBCAT 
DD statement* the JOBCAT catalog(s) is searched. If more 
than one catalog is specified for the job* the catalogs are 
searched in order of concatenation. If the entry is found* 
no other catalog is searched. Otherwise* 

3. If the entry is identified with a qualified entryname and 
its first qualifier is the same as: 

• The name of a user catalog* or 

• The alias of a user catalog* or 

• The alias of an OS CVOL* 

the user catalog or OS CVOL so identified is searched. If . 
the entry is found, no other catalog is searched. ^ A 

Otherwise* \^jr 

4. The master catalog is searched. If the entry is not found, 
a "no entry found" error is returned to the user. 



RETURN CODE CONSIDERATIONS 



The interpretation of catalog management return codes depends on 
whether the request is initiated using a CAMLST macro or a 
catalog parameter list (CPD* and whether the request is 
satisfied in an integrated catalog facility (ICF) catalog, a 
VSAM catalog* or an OS CVOL. 

If CAMLST is used and the request is satisfied in an OS CVOL* 
register 15 contains the OS CVOL return code and registers and 
1 may further describe the return code meaning. If CAMLST is 
used and the request is satisfied in an ICF or a VSAM catalog* 
register 15 contains the OS CVOL return code* register the 
VSAM return code, and register 1 is zero. 

If a CPL is used and the request is satisfied in an OS CVOL, 
register 15 contains the VSAM return code, register is not 
meaningful, and register 1 is nonzero. If a CPL is used and the 
request is satisfied in an ICF or a VSAM catalog* register 15 
contains the VSAM return code. The return code, reason code, 
and module identification can also be found in the CPL. These 
codes are explained in Message Library? System Messages under 
message IDC3009I. 

Note that, regardless of which parameter list is used, if the 
request is satisfied in an ICF or a VSAM catalog* register 1 is 
zero* and if the request is satisfied in an OS CVOL* register 1 
contains X'OB' in the high-order byte and may contain return 
information in the low-order byte. 
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RETRIEVING INFORMATION FROM A CATALOG 

To read an entry from a catalog* use the LOCATE and CAMLST macro 
instructions. You may specify the entry you Mant to read into 
your work area by using either (1) the fully or partially 
qualified name of a data set* or (2) the relative block address 
(TTR) of the block within an OS CVOL containing the entry. If 
you specify a fully qualified data set name* a list of volumes 
on which the data set resides will be read into your work area. 
This volume list always begins with a 2-byte entry that is the 
number of volumes in the list. If the data set resides on more 
than 20 volumes and is cataloged in an OS CVOL* the address of a 
volume control block will follow the volume list entries. (See 
Figure 5 on page 28 for an explanation of the control block.) 

Note: There is a restriction when CAMLST is used to locate a 
data set that is over 20 volumes in length and on a VSAM 
catalog. Only the information from the first 20 volumes is 
returned. 

If you specify a partially qualified data set name, the first 
block in the OS CVOL pointed to by the lowest-level index 
specified will be read into your work area. This is true if you 
specify two or more ifualtfiers* or if you specify the 
CVOL-RELEXP parameter in the CAMLST macro. Register 15 will 
contain return code 12. If you specify a single qualifier and 
do not include the CVOL-RELEXP parameter* the OS CVOL identifier 
'SYSCTLG. Vyyyyyy' is read into your work area (the area 
previously occupied by the data set name). You may then insert 
'yyyyyy* as the CVOL-RELEXP parameter in the CAMLST and reissue 
the LOCATE. 

If you specify a relative block address (TTR)* the block at that 
relative address in the CVOL catalog will be read into your work 
area. 

^ You must add a step when specifying either an unqualified name 

,^y' or the highest level of a partially qualified name to retrieve 

information from an OS CVOL. You receive* instead* the volume 
information for the OS CVOL that is found in the master catalog. 
In addition* the single qualifier name that you specified is 
replaced by the SYSCTLG. Vyyyyyy name. You may then use that 
information to specify the OS CVOL volume serial number in 
CAMLST so that the search starts in the OS CVOL and gives you 
the information that you expected. 

See Figure 1 on page 24 through Figure 8 on page 31 for 
descriptions of the contents of volume control block and the 
other catalog data areas. 

RETRIEVING INFORMATION BY DATA SET NAME (LOCATE AND CAMLST NAME) 

Uhen you specify a data set name* a volume list is built in your 
work area. A volume list consists of ^w entry for each volume 
on which part of the data set resides* it is preceded by a 
2-byte field that contains a count of the number of volumes in 
the list. The count field is followed by a variable number of 
12-byte entries. Each 12-byte entry consists of a 4-byte device 
code* a 6-byte volume serial number* and a 2-byte data set 
sequence number. As many as 20 of these 12-byte entries can be 
built in your work area. (Device codes are presented in the 
UCBTYP data area description of Debugging Handbook .) 

If the named data set is stored on only one volume* bytes 252 
through 254 of your area may contain the relative track address 
of the DSCB for that data set; otherwise* these bytes are zero. 
Byte 255 contains zeros. 

If the data set is cataloged in an OS CVOL and resides on more 
than five volumes* the volume list in your work area is really a 
volume control block (VCB) that has been read into your work 
area. In a VCB* the count field contains the number of volume 
entries in this VCB and any following VCBs. Thus a count of 41 
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indicates tuo folloMing VCBs Mith counts of 21 and one* 
respectively. The relative track address (TTR) of the next VCB 
is in bytes 252 through 254 of your work area. The last VCB for 
a data set has binary zeros in bytes 252 through 254. 

The macro format is? 






[symbol] 
li stname 


LOCATE 
CAMLST 


1 i stname-addrx 

NAME 

,dsname-relexp 

,Cpvol-relexpl 

»area-relexp 



1 i stname-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 



NAME 



this operand must be coded as shown to retrieve information 
from a catalog by name. 



dsname-relexp 

specifies the virtual storage location of a fully qualified 
data set name. The area that contains the name must be 44 
bytes long. The name may be defined by a C-type Define 
Constant (DC) instruction. 

cvol-relexp 

specifies the virtual storage location of the 6-byte volume 
serial number of the OS CVOL to which this catalog request 
is directed. For a discussion of the effect of specifying 
or omitting this operandi see ''Catalog Order of Search" on 
page 2. 

area-relexp 

specifies the virtual storage location of your 265-byte 
work area/ which you must define. The work area must begin 
on a doubleword boundary. 

Example: In the following example^ the catalog entry containing 
a list of the volumes on which data set A.B resides is read into 
virtual storage. 



V^ 





LOCATE INDAB 


X 




X 




X 




^ 




x 




X 




X 






Check Return Codes 


INDAB 


CAMLST NAME, AB,, LOCAREA 


AB 


DC CL44'A.B' 


LOCAREA 


DS OD 




DS 265C 



READ CATALOG ENTRY 
FOR DATA SET A.B 
INTO VIRTUAL STORAGE 
AREA NAMED LOCAREA. 
LOCAREA MAY ALSO 
CONTAIN A 3-BYTE 
TTR AND THE 6-BYTE 
OS CVOL SERIAL NUMBER 



The LOCATE macro instruction points to the CAMLST macro 
instruction. NAME, the first operand of CAMLST, specifies that 
the system is to search for a catalog entry using the name of a 
data set. AB, the second operand, specifies the virtual storage 
location of a 44-byte area into which you have placed the fully 
qualified name of a data set. LOCAREA, the fourth operand, 
specifies a 265-byte area you have reserved in virtual storage. 



o 
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After execution of these macro instructions^ the 265-byte area 
contains a volume list or a volume control block for the data 
set A.B. 

Control Mill be returned to your program at the next executable 
instruction after the LOCATE macro instruction. If the block 
has been successfully read from the catalog^ register 15 Mill 
contain zeros. OtherHise» register 15 Mill contain one of the 
folloMing return codes. 

Code Heaning 

4(04) Either the required catalog does not exist or it cannot 
be opened or there is a closed chain of OS CVOL 
poi nters. 

8(08) One of the folloMing happened: 

• The entry Mas not found. Register contains the 
number of valid index levels if in an OS CVOL. 
Register contains the catalog return code if in 
an ICF or a VSAM catalog. 

• The user is not authorized to perform this 
operation. Register contains hexadecimal 38. 

• A generation data group (GDG) alias Mas found. 
Register contains the number of valid index 
levels. The alias name Mas replaced by the true 
name. 

12(0C) One of the folloNing happened: 

• An index or generation data group base entry Mas 
found Mhen the list of qualified names Mas 
exhausted. Register contains the number of valid 
index levels. The Nork area contains the first 
block of the specified index. 

• An alias entry Has found. The alias name Mas 
replaced in the usier parameter list by the true 
name. 

• An invalid loM-level GDG name Mas found. 

16(10) A data set exists at other than the loMest index level 
specified. Register contains the number of the index 
level Mhere the data set Mas encountered. 

20(14) A syntax error exists in the name. 

24(18) One of the folloMing happened: 

• Permanent I/O error occurred. Register contains 
the VSAM or ICF return code or if in an OS CVOL. 

• Nonzero ESTAE return code. 

• Error in parameter list. 

28(1C) Relative track address supplied to LOCATE routine is 
outside of the SYSCTLG data set extents. 

32(20) Reserved. 

Note: See Message Library: VS2 System Messages * Section 
IDC3009I» for documentation of ICF catalog and VSAM catalog 
return codes. 
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RETRIEVING INFORMATION BY GENERATION DATA SET NAME (LOCATE AND CAMLST NAME) 

You specify the name of a generation data set by using the fully 
qualified generation index name and the relative generation 
number of the data set. The value of a relative generation 
number reflects the position of a data set in a generation data 
group. The follouing values can be used: 

• Zero — specifies the latest data set (highest generation 
number) cataloged in a generation data group. 

• Negative number— specif ies a data set cataloged before the 
latest data set. 

• Positive number — specifies a data set not yet cataloged in 
the generation data group. 

Ulhen you use zero or a negative number as the relative 
generation number* a volume list (or a volume control block) is 
placed in your Mork area* and the relative generation number is 
replaced by the absolute generation name. 

Uhen you use a positive number as the relative generation 
number* an absolute generation name is created and replaces the 
relative generation number. Zeros are read into the first 256 
bytes of your uiork area* because there are no entries in the 
catalog. 

The format is' 



10 tI\ 



t symbol ! 
li stname 



LOCATE 
CAMLST 



li st-addrx 

NAME 

9 dsname-relexp 

» C cvol-relexp ] 

»area-relexp 



li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 






NAME 



this operand must be coded as shoMn in order to read a 
block from the catalog by generation data set name. 



dsname-relexp 

specifies the virtual storage location of the name of the 
generation index and the relative generation number. The 
area that contains these must be 44 bytes long. The name 
may be defined by a C-type define constant (DC) 
instruction. 

cvol-relexp 

specifies the virtual storage location of the 6-byte volume 
serial number of the OS CVOL to Mhich this catalog request 
is directed. For a discussion of the effect of specifying 
or omitting this operand* see "Catalog Order of Search" on 
page 2. 

area-relexp 

specifies the virtual storage location of your 265-byte 
Mork area, uihich you must define. The Mork area must begin 
on a doubleuiord boundary. The first 256 bytes of the work 
area will contain a volume list that is built from the 
catalog. If the data set resides on one volume* bytes 252 
through 254 may contain the relative track address of the 
DSCB. This address is relative to the beginning of the 
volume. 
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Example: In the folloMing example* the list of volumes that 
contain generation data set A.PAY(~3) is read into virtual 
storage. 



INDGX 

APAY 

LOCAREA 



LOCATE 



INDGX 



Check Return Codes 

CAMLST NAME, APAY,, LOCAREA 
DC CL44»A.PAY(-3)» 
DS OD 
DS 265C 



READ CATALOG ENTRY 
FOR DATA SET A.PAY(-3) 
INTO YOUR STORAGE 
AREA NAMED LOCAREA 



^r*\. 



The LOCATE macro instruction points to the CAMLST macro 
instruction. NAME, the first operand of CAMLST, specifies that 
the system is to search the catalog for a catalog entry by using 
the name of a data set. APAY, the second operand, specifies the 
virtual storage location of a 44-byte area into Mhich you have 
placed the name of the generation index and the relative 
generation number of a data set in the generation data group. 
LOCAREA, the fourth operand, specifies a 265-byte area you have 
reserved to receive the catalog information. 

After execution of these macro instructions, the system uill 
have replaced the relative generation number that you specified 
in your 44-byte area with the data set's absolute generation 
name. Control Mill be returned to your program at the next 
executable instruction after the LOCATE macro instruction. If 
the entry has been located and read successfully, register 15 
Nill contain zeros. Otheruise, register 15 Mill contain a 
return code. For a description of the contents of the Mork area 
or the meaning of the exception return codes, see "Retrieving 
Information by Data Set Name (LOCATE and CAMLST NAME)" on page 
3. 



RETRIEVING INFORMATION BY ALIAS C LOCATE AND CAMLST NAME) 



For each of the preceding functions, you can specify an alias as 
the name of a data set. Each function is performed exactly as 
previously described, Mith one exception^ The alias name 
specified is replaced by the true name. 

Note: Aliases are not alloMed for generation data sets 
cataloged in OS CVOLs. 

The format is^ 



[symbol] 
li stname 


LOCATE 
CAMLST 


li st-addrx 

NAME 

* dsname-relexp 

ftcvol-relexp] 

»area-relexp 



li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 






NAME 



this operand must be coded as shoMn to retrieve information 
from a catalog. 
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dsname-relexp 

specifies the virtual storage location of a fully qualified 
data set name* the first or only name of Mhich is the 
alias. The area that contains the name must be 44 bytes 
long. The name may be defined by a C-type define constant 
(DC) instruction. 

cvol-relexp 

specifies the virtual storage location of the 6-byte volume 
serial number of the OS CVOL to which this catalog request 
is directed. For a discussion of the effect of specifying 
or omitting this operand* see "Catalog Order of Search" on 
page 2. 

area-relexp 

specifies the virtual storage location of your 265-byte 
Mork area» Mhich you must define. The Mork area must begin 
on a doubleword boundary. The first 256 bytes of the work 
area will contain a volume list that is read from a 
catalog. If the data set resides on one volume* bytes 252 
through 254 may contain the relative track address of the 
DSCB. This address is relative to the beginning of the 
volume. 

Example: In the following example* the catalog entry containing 
a list of the volumes on which data set A.B.C resides is read 
into virtual storage (data set A.B.C* however* is addressed by 
an alias name* X.B.C). 



READ CATALOG ENTRY 
FOR DATA SET X.B.C 
INTO VIRTUAL STORAGE 
AREA NAMED LOCAREA. 





LOCATE INDAB 


Check Return codes 


INDAB 

ABC 

LOCAREA 


CAMLST NAME* ABC* LOCAREA 
DC CL44»X.B.C' 
DS OD 
DS 265C 



The LOCATE macro instruction points to the CAMLST macro 
instruction. NAME* the first operand of CAMLST, specifies that 
the system is to search the catalog for an entry using the name 
of a data set. ABC* the second operand* specifies the virtual 
storage location of a 44-byte area into which you have placed 
the fully qualified name of a data set (in this case* data set 
A.B.C is addressed by its alias X.B.C). LOCAREA* the fourth 
operand* specifies a 265--'byte area you have reserved in virtual 
storage. 

For information on return codes and the contents of your work 
area after execution* see "Retrieving Information by Data Set 
Name (LOCATE and CAMLST NAME)" on page 3. 

READING A BLOCK BY RELATIVE BLOCK ADDRESS (LOCATE AND CAHLST BLOCK) 

You can read any block in an OS CVOL by specifying* in the form 
TTR* the identification of the block and its location relative 
to the beginning of the catalog. TT is the number of tracks 
from the beginning of the catalog* R is the record number of the 
desired block on the track. 



o 
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The format is^ 



IsymboU 
listname 


LOCATE 
CAMLST 


|i st-addrx 

BLOCK 

»ttr-rclexp 

,9vol-relexp 

•area-relexp 



n^t-^ddrx 

points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 



BLOCK 

you must code this operand as shouin. 

i;tr-relexp 

specifies the virtual storage location of a 3-byte relative 
block address (TTR). This address indicates the position 
relative to the beginning of the catalog data set^ of the 
track containing the block (TT)f and the block 
identification <R) on that track. 

cvol-relexp 

specifies the virtual storage location of a 6-byte volume 
serial number for the volume to be processed. 

I>r?a-relexp 

specifies the virtual storage location of your 265-byte 
uork area» Mhich you must define. The Mork area must begin 
on a doubleujord boundary. The first 256 bytes of the work 
area uiill contain the block that is read from the catalog^ 
and the last 6 bytes Mill contain the serial number of the 
volume on Mhich the block Mas found. If the data set 
resides on one volume> bytes 252 through 254 Mill contain 
the relative track address of the DSCB. 

Example: In the folloMing example* the block at the location 
indicated by TTR is read into virtual storage. 



LOCATE ELK 
Check Return Codes 



ELK 


CA 


X 




x 




TTR 


DC 




DC 


VOLSER 


DC 


LOCAREA 


DS 




DS 



BLOCK, TTR, VOLSER, LOCAREA 

READ A BLOCK INTO 
VIRTUAL STORAGE AREA 
H'5' RELATIVE TRACK 5 

X»03» BLOCK 3 ON TRACK 

CUlllll' VOLUME SERIAL OF OS CVOL 

OD NAMED LOCAREA 

265C LOCAREA ALSO CONTAINS 

6-BYTE SERIAL NO. 



The LOCATE macro instruction points to the CAMLST macro 
instruction. BLOCK, the first operand of CAMLST, specifies that 
the system i s to search the catalog for the block indicated by 
TTR, the second operand. VOLSER, the third operand, specifies 
the virtual storage location of a 6-byte volume serial number 
for the volume to be processed. LOCAREA, the fourth operand, 
specifies a 265-byte area you have reserved in virtual storage. 

After execution of these macro instructions, the 265-byte area 
contains: the 256-byte block and the 6-byte serial number of the 
volume on Mhich the block Mas found (in bytes 259 through 264). 
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Control Mill be returned to your program at the next executable 
instruction following the LOCATE macro instruction. If the 
index block at the address you specified has been successfully 
located and read intq your Mork area» register 15 Mill contain 
zeros. OtherMise^ register 15 Mill contain one of the exception 
return codes described under "Retrieving Information by Data Set 
Name (LOCATE and CAMLST NAME)" on page 3. 






BUILDING AND DELETING INDEXES 



You handle OS CVOL indexes — build them* delete them» and so 
forth — by using combinations of the INDEX and CAMLST macro 
instructi ons. 



BUILDING AN INDEX (INDEX AND CAMLST BLDX) 



To build a neN OS CVOL index structure and add it to the 
catalog* you may create each level of the index separately. 
(You can also create index levels Mhile you are cataloging a 
data set onto those index levels. To create each level of the 
index* use the INDEX and CAMLST macro instructions.) 

These tMo macro instructions can also be used to add index 
levels to existing index structures. 

The format is? 



[symbol] 
listname 


INDEX 
CANL3T 


list-addrx 
BLDX 

»namerelexp 
ticvol-relexpl 



li st-addrx 

points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 






BLDX 



this operand must be coded as shoMn. 



namerelexp 

specifies the virtual storage location of the fully 
qualified name of a data set or index level. The name 
cannot exceed 44 characters. If the name is less than 
characters* it must be folloNed by at least one blank, 
name may be defined by a C-type define constant (DC) 
instruction. 



The 



cvol-relexp 

specifies the virtual storage location of a 6-byte volume 
serial number of the OS CVOL to Mhich this catalog request 
is directed. For a discussion of the effect of specifying 
or omitting this operand* see "Catalog Order of Search" on 
page 2. 

Example* In the folloMing example* index structure A.B.C is 
built on the OS CVOL Mhose serial number is 000045. 

Each INDEX macro instruction points to an associated CAMLST 
macro instruction. BLDX* the first operand of CAMLST* specifies 
that an index level be built. The second operand specifies the 
virtual storage location of the area into Mhich you have placed 
the fully qualified name of an index level. The third operand 
specifies the virtual storage location of the area into Mhich 
you have placed the 6-byte serial number of the volume on Mhich 
the index level is to be built. 
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INDEX INDEXA 
Check Return Codes 

INDEX INDEXB 

Check Return Codes 



INDEX 



INDEXC 



BUILD INDEX A 



BUILD INDEX STRUCTURE 
A.B 



BUILD INDEX STRUCTURE 
A.B.C 



Check Return Codes 



INDEXA 


CAMLST 


INDEXB 


CAMLST 


INDEXC 


CAMLST 


VOLNUM 


DC 


ALEVEL 


DC 


BLEVEL 


DC 


CLEVEL 


DC 



BLDX, ALEVEL, VOLNUM 

BLDX, BLEVEL, VOLNUM 

BLDX, CLEVEL, VOLNUM 

CL6'000045' VOLUME SERIAL NUMBER 

CL2'A» INDEX STRUCTURE NAMES 

CL4'A.B' FOLLOWED BY A BLANK 

CL6'A.B.C' WHICH DELIMITS FIELDS 



^iltalLJ 






Control will be returned to your program at the next executable 
instruction following the INDEX macro instruction. If the index 
has been built successfully, register 15 will contain zeros. 
Otherwise, register 15 will contain one of the following 
exception return codes* 

Code Meaning 

4(04) The OS CVOL does not exist or cannot be opened. 

8(08) One of the following happened^ 

• The existing catalog structure is inconsistent with 
the operation requested. If the error was detected 
while processing in an OS CVOL, register has the 
number of valid index levels and register 1 has the 
return code that would have resulted if a LOCATE 
macro had been issued on the same entry name. If 
the error was detected during the master catalog 
search process, register contains the catalog 
return code and register 1 contains zero. 

• The user is not authorized to perform the 
operation. Register contains 56 (decimal); 
register 1 contains 0. 

12(0C) An attempt was made to build an index or generation 
index that has an alias or has indexes or data sets 
cataloged under it. The index is unchanged. 

16(10) The qualified name specified when building an index or 
generation index implies an index structure that does 
not exist; the high-level index, specified when 
connecting control volumes, does not exist. 

20(14) Space is not available on the specified OS CVOL. 

24(18) Not used with the INDEX macro instruction. 

28(1C) A permanent I/O error was found when processing the 
catalog, or a nonzero return code from ESTAE was 
encountered. 
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BUILDING A GENERATION INDEX (INDEX AND CANLST BLDG) 



You build a generation index in an OS CVOL by using the INDEX 
and CAMLST macro instructions. All higher levels of the index 
must exist. If the higher levels of the index are not in the 
catalog^ you must build them. Hom to build an index has been 
explained previously. 

The format is^ 



[svmbol] 
li stname 


INDEX 
CAKLST 


li st-addrx 

BLDG 

•namerelexp 

* [cvol-relexp] 

,, [DELETE] 

, [EMPTY] 

9 number-absexp 



li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 



BLDG 



this operand must be coded as shoujn. 



namerelexp 

specifies the virtual storage location of the fully 
qualified name of a data set or index level. The name 
cannot exceed 44 characters. If the name is less than 44 
characters^ it must be followed by at least one blank. The 
name may be defined by a C-type define constant (DC) 
instruction. 

cvol-relexp 

specifies the virtual storage location of a 6-byte volume 
serial number of the OS CVOL to which this catalog request 
is directed. For a discussion of the effect of specifying 
or omitting this operandi see "Catalog Order of Search" on 
page 2. 

DELETE 

specifies that all data sets on direct access volumes that 
are removed from a generation data group are to be deleted^ 
that is» the space allocated to the data set(s) is to be 
made available for reallocation. A SCRATCH macro 
instruction will be issued by the catalog management 
routines to delete the data set» which will be deleted from 
the volume if there are no conditions preventing deletion 
(for example^ expiration date not passed* password not 
verified, volume not mounted* permanent I/O error 
encountered while trying to delete the data set). 

EMPTY 

specifies that references to all data sets in a generation 
data group cataloged in the generation index are to be 
removed from the index when the number of entries specified 
is exceeded. 

number-absexp 

specifies the number of data sets to be included in a 
generation data group. This number must be specified, and 
cannot exceed 255. 






Example: In this example, generatio 
CVOL, serial number 000045. The hi 
already exist. Uhen the number of 
generation index D exceeds four, th 
uncataloged. Uhen the DELETE opera 
data set has been successfully unca 
management routines issue a SCRATCH 
Managing the Volume Table of Conten 
delete the data set. If there are 



n index D is built on the OS 
gher-level indexes A.B.C 
generation data sets in the 
e oldest data set is 
nd has been specified and the 
taloged, the catalog 

macro (see "Chapter 2. 
ts (VTOC)" on page 33) to 
no conditions preventing the 



c 
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data set from being deleted (for example* the expiration date 
Mas not passed* the password could not be verified* or a 
permanent I/O error Mas encountered Mhen trying to delete the 
data set)* the data set Mill be deleted. 



^y 



INDEX GENINDX 
Check Return Codes 



BUILD GENERATION INDEX 



GENINDX CAMLST BLDG*DLEVEL* VOLNUM, , DELETE, ,4 
DLEVEL DC CL8»A.B.C.D • ONE BLANK* DELIMITER 
VOLNUM DC CL6'000045' 



The INDEX macro instruction points to the CAMLST macro 
instruction. BLDG* the first operand of CAMLST* specifies that 
a generation index is to be built. DLEVEL* the second operand* 
specifies the virtual storage location of an area into Mhich you 
have placed the fully qualified name of a generation index. 
VOLNUM* the third operand* specifies the virtual storage 
location of the area into Mhich you have placed the 6~byte 
serial number of the volume on Mhich the generation index i s to 
be built. DELETE* the fifth operand* specifies that all data 
sets dropped from the generation data group are to be deleted. 
The final operand* 4* specifies the number of data sets that are 
to be maintained in the generation data group. Control Mill be 
returned to your program at the next executable instruction 
following the INDEX macro instruction. If the generation index 
Mas built successfully* register 15 contains zeros. OtherMise* 
register 15 Mill contain one of the exception .return codes 
described under "Building an Index (INDEX and CAMLST BLDX)" on 
page 10. 



DELETING AN INDEX (INDEX AND CANLST DLTX) 



You can delete any number of index levels from an existing OS 
CVOL index structure. Each level of the index is deleted 
separately. Generation indexes are also removed this May. (You 
can also delete index levels automatically Mhen you uncatalog a 
data set.) You delete each level of the index by using the 
INDEX and CAMLST macro instructions. 

If an index level either has an alias* or has other index levels 
or data sets cataloged under it* it cannot be deleted. 

The format is? 



I, symbol 1 

listname 


INDEX 
CANLST 


list-addrx 
DLTX 

•namerelexp 
[f cvol-relexpl 



o 



li st-addrx 

points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 



DLTX 



this operand must be coded as shoMn. 



namerelexp 

specifies the virtual storage location of the fully 
qualified name of a data set or index level. The name 
cannot exceed 44 characters. If the name is less than 44 
characters* it must be folloMed by at least one blank, 
name may be defined by a C~type define constant (DC) 
instruction. 



The 
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cvol-relexp 

specifies the virtual storage location of a 6-byte volume 
serial number of the OS CVOL to Mhich this catalog request 
is directed. For a discussion of the effect of specifying 
or omitting this operand* see "Catalog Order of Search" on 
page 2. 

Example: In the following example* index level C is deleted from 
index structure A. B.C. 



( 








INDEX DELETE 


DELETE INDEX LEVEL 


X 




C FROM INDEX STRUCTURE 


Ik 


Check Return Codes 


A.B.C 


DELETE 


CAMLST DLTX, LEVELC 




LEVELC 


DC CL6'A.B.C' 


ONE BLANK FOR 


x 




DELIMITER 



The INDEX macro instruction points to the CAMLST macro 
instruction. DLTX, the first operand of CAMLST, specifies that 
an index level be deleted. LEVELC, the second operand, 
specifies the virtual storage location of the area into Mhich 
you have placed the fully qualified name of the index structure 
Mhose lowest level is to be deleted. Control will be returned 
to your program at the next executable instruction following the 
INDEX macro instruction. If the index level(s) was successfully 
deleted, register 15 contains zeros. Otherwise, register 15 
contains one of the exception return codes described under 
"Building an Index (INDEX and CAMLST BLDX)" on page 10. 



ASSIGNING AN ALIAS FOR AN INDEX (INDEX AND CANLST BLDA) 






For OS CVOLs you assign SiX\ alias to an index level by using the 
INDEX and CAMLST macro instructions. An alias can be assigned 
only to a high level index; for example, index A of index 
structure A.B.C can have an alias, but index B cannot. 
Assigning an alias to a high level index effectively provides 
aliases for all data sets cataloged under that index. An alias 
cannot be assigned to a generation index. 

The format is? 



[symbol 3 
li stname 


INDEX 
CAHLST 


list-addrx 

BLDA 

, index namerelexp 

»tcvol-relexp] 

•alias namerelexp 



li st-addrx 

points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 



BLDA 



this operand must be coded as shown. 



index namerelexp 

specifies the virtual storage location of the name of a 
high-level index. The &ri&Sk that contains the name must be 
8 bytes long. The name may be defined by a C~type define 
constant (DC) instruction. 

cvol-relexp 

specifies the virtual storage location of a 6-byte volume 
serial number of the OS CVOL catalog to which this catalog 
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request is directed. For a discussion of the effect of 
specifying or omitting this operand* see "Catalog Order of 
Search" on page 2. 

alias namerelexp 

specifies the virtual storage location of the name that is 
to be used as an alias for a high-level index. The area 
that contains the name must be 8 bytes long. The name may 
be defined by a C-type define constant (DC) instruction. 

Example: In the following example* high-level index A is 
assigned an alias of X. 



INDEX 



ALIAS 



BUILD AN ALIAS FOR 
A HIGH LEVEL INDEX 



Check Return Codes 



ALIAS 


CAMLST 


DSNAME 


DC 


DSALIAS 


DC 



BLDA, DSNAME, *DSALIAS 
CLS'A* MUST 

CL8»X» 



BE 8-BYTE FIELDS 






The INDEX macro instruction points to the CAMLST macro 
instruction. BLDA» the first operand of CAMLST, specifies that 
an alias be built. DSNAME, the second operand, specifies the 
virtual storage location of an 8-byte area into which you have 
placed the name of the high-level index to be assigned an alias. 
DSALIAS, the fourth operand, specifies the virtual storage 
location of an 8-byte area into which you have placed the alias 
to be assigned. 

Control will be returned to your program at the next executable 
instruction following the INDEX macro instruction. If the alias 
has been successfully assigned, register 15 will contain zeros. 
Otherwise, register 15 will contain one of the exception return 
codes described under "Building an Index (INDEX and CAMLST 
BLDX)" on page 10. 



DELETING AN ALIAS FOR AN INDEX (INDEX AND CAMLST DLTA) 



For OS CVOLs you can delete an alias previously assigned to a 
high-level index by using the INDEX and CAMLST macro 
instructions. 

The format is^ 



[symbol] 
li stname 


INDEX 
CAMLST 


list-addrx 

DLTA 

talias namerelexp 

t»cvol-relexp3 



li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 



DLTA 



this operand must be coded as shown. 



alias namerelexp 

specifies the virtual storage location of the name that is 
used as an alias for a high-level index. The area that 
contains the name must be 8 bytes long. The name may be 
defined by a C-type define constant (DC) instruction. 
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cvol-relexp 

specifies the virtual storage location of a 6-byte volume 
serial number of the OS CVOL catalog to Mhich this catalog 
request is directed. For a discussion of the effect of 
specifying or omitting this operandi see "Catalog Order of 
Search" on page 2. 

Example! in the following example* alias X» previously assigned 
as an alias for index level A» is deleted. 



G 



INDEX 



DELALIAS 



DELETE AN ALIAS FOR 
A HIGH LEVEL INDEX 



Check Return codes 



DELALIAS 
ALIAS 



CAMLST 
DC 



DLTA»ALIAS 
CL8*X' 



MUST BE 8-BYTE FIELD 



The INDEX macro instruction points to the CAMLST macro 
instruction. DLTA» the first operand of CAMLST» specifies that 
an alias be deleted. ALIAS* the second operand* specifies the 
virtual storage location of the S-byte area into Mhich you have 
placed the alias to be deleted. 



CONNECTING AND DISCONNECTING OS CVOLS 



You connect and disconnect OS CVOLs by using combinations of the 
INDEX and CAMLST macro instructions. 



CONNECTING OS CVOLS (INDEX AND CANLST LNKX) 



You connect tvio OS CVOLs by using the INDEX and CAMLST macro 
instructions. 






You must supply the serial number of the volume to be connected 
and the high-level index name that Mill be used to associate the 
tMo volumes. If the index name is an alias of an OS CVOL 
pointer entry in the master catalog* then the serial number of 
the "from" volume may be omitted. OtherMise* you must supply 
the serial numbers of both volumes and the name of a high-level 
index associated Mith the volume to be connected. 

The result of connecting OS CVOLs is that the volume serial 
number of the OS CVOL connected and the name of a high-level 
index are entered into the volume index of the volume to Mhich 
it Mas connected. This entry is called a control-volume 
pointer. 

The format iss 



CsymboU 
li stname 


INDEX 
CANLST 


list-addrx 

LNKX 

, index namerelexp 

» Ccvol-relexpj 

tnew cvol-relexp 



li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 



LNKX 



this operand must be coded as shoMn. 



o 



16 MVS/370 System Programming Library: Data Management 



o 



index namerelexp 

specifies the virtual storage location of the name of a 
high-level index. The area that contains the name must be 
8 bytes long. The name may be defined by a C-type define 
constant (DC) instruction. 

cvol-relexp 

specifies the virtual storage location of a S-byte volume 
serial number of the OS CVOL catalog to uihich this catalog 
request is directed. For a discussion of the effect of 
specifying or omitting this operand* see "Catalog Order of 
Search** on page 2. 

new cvol-relexp 

specifies the virtual storage location of the 4-byte device 
code and S-byte volume serial number of the control volume 
that is to be connected to another OS CVOL. 

Example: In the following example* the OS CVOL Mhose serial 
number is 001555 is connected to the OS CVOL numbered 000155. 
The name of the high-level index is HIGHINDX. 



INDEX 



CONNECT 






X 
X 

)( 


Check Return Codes 


CONNECT 

INDXNAME 

OLDCVOL 

NEMCVOL 


CAMLST 


LNKX, INDXNAME 


DC 
DC 
DC 
DC 


CL8'HIGHINDX' 
CL6»000155» 
X'30C0200D« 
CL6»001555' 



CONNECT TWO OS CVOLS 
UHOSE SERIAL NUMBERS ARE 
000155 and 001555. 
3330 DISK DEVICE CODE 



The INDEX macro instruction points to the CAMLST macro 
instruction. LNKX» the first operand of CAMLST* specifies that 
control volumes be connected. INDXNAME* the second operand* 
specifies the virtual storage location of the S-byte area into 
which you have placed the name of the high-level index of the 
volume to be connected. OLDCVOL* the third operand* specifies 
the virtual storage location of a 6-byte area into which you 
have placed the serial number of the volume to which you are 
connecting. 

NEMCVOL* the fourth operand* specifies the virtual storage 
location of a 10-byte area into which you have placed the 4-byte 
hexadecimal device code of the volume to be connected followed 
by the 6-byte area to contain the volume serial number of the 
volume to be connected. 

Control will be returned to your program at the next executable 
instruction following the INDEX macro instruction. If the OS 
CVOLs have been successfully connected* register 15 will contain 
zeros. Otherwise* register 15 will contain one of the exception 
return codes described under "Building an Index (INDEX and 
CAMLST BLDX)" on page 10. 



DISCONNECTING OS CVOLS (INDEX AND CANLST DRPXl 






You disconnect two OS CVOLs by using the INDEX and CAMLST macro 
instructions. 

The result of disconnecting OS CVOLs is that the OS CVOL pointer 
is removed from the volume index of the volume from which you 
are disconnecting. 
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The format \s' 



[symbol] 
li stname 


INDEX 
CAHLST 


list-addrx 

DRPX 

•index namerelexp 

IfCvol-relexpl 






li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 



DRPX 



this operand must be coded as shoMn. 



index namerelexp 

specifies the virtual storage location of the name of a 
high-level index. The area that contains the name must be 
8 bytes long. The name may be defined by a C-type define 
constant (DC) instruction. 

cvol-relexp 

specifies the virtual storage location of a 6-byte volume 
serial number of the OS CVOL catalog to Mhich this catalog 
request is directed. For a discussion of the effect of 
specifying or omitting this operand* see "Catalog Order of 
Search" on page 2. 

Example: in the following example, the OS CVOL that contains the 
high-level index HIGHINDX is disconnected from the OS CVOL 
pointed to by the entry 'HIGHINDX' in the master catalog. 



INDEX 



DISCNECT 



Check Return Codes 

DISCNECT CAMLST DRPX, INDXNAME 
INDXNAME DC CLS'HIGHINDX' 



DISCONNECT TWO 
OS CVOLS 



MUST BE 8-BYTE FIELD 






The INDEX macro instruction points to the CAMLST macro 
instruction. DRPX, the first operand of CAMLST, specifies that 
OS CVOLs be disconnected. INDXNAME, the second operand, 
specifies the virtual storage location of the 8-byte area into 
Mhich you have placed the name of the high-level index of the OS 
CVOL to be disconnected. 

Control Mill be returned to your program at the next executable 
instruction folloMing the INDEX macro instruction. If the OS 
CVOLs Mere successfully disconnected, register 15 Mill contain 
zeros. OtherMise, register 15 Mill contain one of the exception 
return codes described under "Building an Index (INDEX and 
CAMLST BLDX)" on page 10. 



WORKING mtH NON-VSAM DATA SET CATALOG ENTRIES 



You can catalog, uncatalog, and recatalog non-VSAM data sets in 
OS CVOLs, ICF catalogs, and VSAM catalogs by using combinations 
of the CATALOG and CAMLST macro instructions. CATALOG macro 
instructions are used to point to CAMLST macro instructions; 
CAMLST macro instructions are used to specify cataloging 
options. 

To catalog non-VSAM data sets in ICF or VSAM catalogs, the 
search algorithm is the same as that given in the section "Order 
of Catalog Selection for DEFINE" in the Access Method Services 
Reference . To uncatalog or recatalog non-VSAM data sets in ICF 



o 
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or VSAM catalogs^ the search algorithm is the same as that given 
in the section "Order of Catalog Search for DELETE" in Access 
Method Services Reference . 

CATALOGING A NON-VSAN DATA SET (CATALOG AND CANLST CAT) 

The format of the CATALOG and CAMLST macros is^ 



[ symbol ] 
listnajne 



CATALOG 
CAMLST 



li st-addrx 

CATCBXl 

> name-relexp 

9 [ cvol-relexp ] 

> vol list-relexp 

I,DSCBTTR= d5cb ttr-relexp 3 



J 



li st-addrx 

points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 

CATCBX] 

this operand must be coded as shoMn. Either CAT or CATBX 
may be coded; but» in either case» missing indexes uithin 
an OS CVOL are always automatically created. 

name-relexp 

specifies the virtual storage location of the fully 
qualified name of a data set. The name cannot exceed 4^ 
characters. If the name is less than 44 characters* it 
must be followed by at least one blank. The name may be 
defined by a ^C-type define constant (DC) instruction. 

cvol-relexp 

specifies the virtual storage location of the 6-byte volume 
serial number of the OS CVOL catalog to which this catalog 
request is directed. For a discussion of the effect of 
specifying or omitting this operand* see "Building an Index 
(INDEX and CAMLST BLDX)" on page 10. 



vol list-relexp 

specifies the virtual storage 
contains a volume list. The 1 
boundary and consist of an ent 
the data set is stored. The f 
indicate the number of entries 
number cannot be zero. Each 1 
consists of a 4-byte device co 
number* and a 2-byte data set 
sequence number is always zero 
(Device codes are presented in 



location of an area that 
i st must begin on a halfword 
ry for each volume on which 
irst two bytes of the list 

in the volume list; the 
2-byte volume list entry 
de, a 6-byte volume serial 
sequence number. The 

for direct access volumes. 

Debugging Handbook . ) 



DSCBTTR= d5cb ttr-relexp 

specifies the virtual storage location of the 3-byte 
relative track address (TTR) of the format-1 data set 
control block (DSCB) for a data set that resides on only 
one volume. The address is relative to the beginning of 
the volume. 



Programming Considerations for Multiple-Step Jobs 



Uhen you are executing multiple-step jobs* it is preferable to 
catalog or uncatalog data sets using JCL* instead of using 
lEHPROGM or a user program. Since ALLOCATION/UNALLOCATION 
monitors data sets during job execution* and it is not aware of 
the functions performed by the user programs, conflicting 
functions can be performed or GDG orientation can be lost. 

UNALLOCATION recatalogs existing cataloged data sets at job 
termination. This action occurs because the data set is opened 
sometime during the job and the DSCB TTR was not found in the 
catalog entry. Therefore* if you &m using the CAMLST macro to 
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uncatalog and then catalog data sets Mith new volume 
information^ be sure to include the DSCB TTR. 

Example: In the folloNing example^ the non-VSAM data set named 
A.B.C is cataloged. The data set i s stored on tMO volumes. 






CATALOG ADDABC 
Check Return Codes 



CATALOG DATA SET A.B.C 



ADDABC 


CAMLST 


CAT, DSNAME, 


DSNAME 


DC 


CL6»A.B.C' 


VOLUMES 


DC 


H'2' 




DC 


X»30C0200D' 




DC 


CL6»000014» 




DC 


H'O* 




DC 


X»30C0200D» 




DC 


CL6»000015' 




DC 


H»0' 



ONE BLANK FOR DELIMITER 
DATA SET ON TWO VOLUMES 
3330 DISK DEVICE CODE 
VOLUME SERIAL NUMBER 
DATA SET SEQUENCE NUMBER 
3330 DISK DEVICE CODE 
VOLUME SERIAL NUMBER 
SEQUENCE NUMBER 



The CATALOG macro instruction points to the CAMLST macro 
instruction. CAT, the first operand of CAMLST, specifies that a 
data set is to be cataloged. DSNAME, the second operand, 
specifies the virtual storage location of the area in which the 
data set name A.B.C uias placed. VOLUMES, the fourth operand, 
specifies the virtual storage location of the volume list that 
Mas built. 

Control Mill be returned at the instruction folloMing the 
CATALOG macro instruction. If A.B.C Mas successfully cataloged, 
register 15 Mill contain zeros. OtherMise, register 15 Mill 
contain one of the following return codes^ 

Code Meaning 

4(04) Either the required catalog does not exist, it is not 
open, or the "do not allocate" bit is on. 

8(08) One of the folloNing happened^ 

• The existing catalog structure is inconsistent Mith 
the operation requested. If the error was detected 
Mhile processing in an OS CVOL, register has the 
number of valid index levels and register 1 has the 
return code that Mould have resulted if a LOCATE 
macro had been issued for the same entry name. If 
the error Mas detected in an ICF or a VSAM catalog, 
register contains the catalog return code and 
register 1 contains zero. 

• The user is not authorized to perform the 
operation. Register contains decimal 56 (X"'36') 
and register 1 contains zero. 

12(0C) Not used Mith the CATALOG macro instruction. 

16(10) The index structure necessary to catalog the data set 
does not exi st . 

20(14) There is insufficient space on the catalog data set. 

24(18) An attempt Mas made to catalog an improperly named 

generation data set, or the generation index is full 
and the named data set is older than any currently in 
the index. 






28(1C) One of the folloMing happened: 



20 MVS/370 System Programming Library: Data Management 



A permanent I/O or unrecoverable error Mas 
encountered. 

An error Mas found in a parameter list. 

An I/O error occurred in an OS CVOL. 

There Mas a nonzero return code from ESTAE. 



UNCATALOGXNG A NON-VSAH DATA SET (CATALOG AND CANLST UNCAT) 



When the UNCAT or UCATDX operand of the CAMLST macro instruction 
is used» a data set reference and unneeded indexes* Mith the 
exception of the highest-level index» are removed. 

The format of the CATALOG and CAMLST macros is^ 



[symbol] 
li^tpam? 


CATALOG 
CAMLST 


li st-addrx 
UNCAT or UCATDX 
tname-relexp 
l»cvol-relexp3 






li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 

UNCAT or UCATDX 

this operand must be coded as shoMn. Either UNCAT or 
UCATDX may be coded but in either case unneeded indexes » 
Mith the exception of the highest-level index* are alMays 
removed along Mith the data set reference. . 

name-relexp 

specifies the virtual storage location of the fully 
qualified name of a data set or index level. The name 
cannot exceed 44 characters. If the name is less than 44 
characters* it must be folloMed by at least one blank. The 
name may be defined by a C-type define constant (DC) 
instruction. 

cvol-relexp 

specifies the virtual storage location of the 6-byte volume 
serial number of the OS CVOL catalog to Mhich this catalog 
request is directed. For a discussion of the effect of 
specifying or omitting this operand* see "Catalog Order of 
Search" on page 2. 

In the folloHing example* the catalog entry for data set A.B.C 
is removed from a catalog. In an OS CVOL* index B is removed 
unless it contains references to other data sets^ Index A 
remains because it is the highest-level index. 



REMOVE 
DSNAME 



CATALOG REMOVE 



Check Return Codes 



CAMLST 
DC 



UNCAT*DSNAME 
CL6»A.B.C' 



REMOVE REFERENCES TO 
DATA SET A.B.C FROM 
CATALOG 



ONE BLANK FOR DELIMITER 



The CATALOG macro instruction points to the CAMLST macro 
instruction. UNCAT* the first operand of CAMLST* specifies that 
references to a data set be removed from the catalog. DSNAME* 
the second operand* specifies the virtual storage location of an 
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area into Mhich you have placed the fully qualified name of the 
data set Mhose references are to be removed. 

Control will be returned to your program at the instruction 
folloMing the CATALOG macro instruction. If your data set has 
been successfully uncataloged» register 15 Mill contain zeros. 
OtherMise» register 15 Mill contain one of the return codes 
described under "Cataloging a Non-VSAM Data Set (CATALOG and 
CAMLST CAT)" on page 19. 



\,.y 



RECATALOGING A NON-VSAN DATA SET (CATALOG AND CAMLST RECAT) 



You can recatalog a cataloged non-VSAM data set by using the 
CATALOG and CAMLST macro instructions. Recataloging is usually 
necessary if a data set is extended to a neM volume. 

As in the original cataloging procedure^ you must build a 
complete volume list in virtual storage. This volume list 
consists of an entry for each volume on Mhich the data set 
resides. The first 2 bytes of the list indicate the number of 
entries in the list; the number may not be zero. Each 12-byte 
volume pointer consists of a 4-byte device code» a 6-byte volume 
serial number » and a 2-byte data set sequence number. The 
sequence number is always zero for direct access volumes. 
(Device codes are presented in Debugging Handbook .) 

The format of the CATALOG and CAMLST macros is: 



[ symbol 3 
li stname 



CATALOG 
CAMLST 



li st-addrx 

RECAT 

» name-relexp 

r [ cvol-relexp 3 

» vol list-relexp 

[ , DSCBTTR= d5cb ttr-relexp 3 



li st-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 






RECAT 



this operand must be coded as shoMn 



name-relexp 

specifies the virtual storage location of the fully 
qualified name of a data set. The name cannot exceed 44 
characters. If the name is less then 44 characters, it 
must be followed by at least one blank. The name may be 
defined by a C-type define constant (DC) instruction. 

cvol~relexp 

specifies the virtual storage location of the S-byte volume 
serial number of the OS CVOL catalog to Mhich this catalog 
request is directed. For a discussion of the effect of 
specifying or omitting this operand, see "Catalog Order of 
Search" on page 2. 

vol list-relexp 

specifies the virtual storage location of an area that 
contains a volume list. The area must begin on a half-Mord 
boundary. 

DSCBTTR= dscb ttr-relexp 

specifies the virtual storage location of the 3-byte 
relative track address (TTR) of the identifier (format-1) 
DSCB for a data set that resides on only one volume. The 
address is relative to the beginning of the volume. 

Example: In the following example, the two-volume data set named 
A.B.C is recataloged to add a third volume. An entry is added 
to the volume list, which previously contained only two entries. 



o 
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^^ulir 





CATALOG 


RECATLG 


RECATALOG DATA SET 


X 








A.B.C ADDING A NEU 


x 








VOLUME 




Check 


Return Codes 




RECATLG 


CAMLST 


RECAT» DSNAME, 


, VOLUMES 


DSNAME 


DC 




CL6'A.B.C • 


FOR DELIMITER ONE BLANK 


VOLUMES 


DC 




H'3'' 


THREE VOLUMES 




DC 




X»30C0200D' 


3330 DISK DEVICE CODE 




DC 




CL6'000014' 


VOLUME SERIAL NUMBER 




DC 




H»0' 


SEQUENCE NUMBER 




DC 




X'30C0200D' 


3330 DISK DEVICE CODE 




DC 




CL6*000015' 


VOLUME SERIAL NUMBER 




DC 




H'O* 


SEQUENCE NUMBER 




DC 




X»30C0200D' 


3330 DISK DEVICE CODE 




DC 




CL6»000016' 


VOLUME SERIAL NUMBER 




DC 




H'O* 


SEQUENCE NUMBER 



The CATALOG macro instruction points to the CAMLST macro 
instruction. RECAT» the first operand of CAMLST, specifies that 
a data set be recataloged. DSNAME, the second operand, 
specifies the virtual storage location of an area into which you 
have placed the fully qualified name of the data set to be 
recataloged. VOLUMES, the fourth operand, specifies the virtual 
storage location of the volume list you have built. 

Control Mill be returned to your program at the instruction 
following the CATALOG macro instruction. If the data set has 
been successfully recataloged, register 15 Mill contain zeros. 
Otherwise, register 15 will contain one of the return codes 
described under "Cataloging a Non-VSAM Data Set (CATALOG and 
CAMLST CAT)" on page 19. 



Chapter 1. Using Catalog Management Macro Instructions 23 



OS CVOL ENTRY FORMATS 



This section describes the format and contents of each of the fY, 
entries that may appear in the OS CVOL. '%^ 



OS CVOL VOLUME INDEX CONTROL ENTRY 



Field 1 

X'0000000000000001« 
Name 


Field 2 

TTR of last 
block in 
volume index 


Field 3 

X»05» 
Count 



11 



12 



Field 4 

TTR of 
last block 
in SYSCTLG 
data set 


Field 5 

x»oo* 


Field 6 

TTR of first 
unused block 
in SYSCTLG 
data set 


Field 7 

x»oa» 


Field 8 

Unused 
bytes 



12 




Field 


l: 


Field 


2: 


Field 


3: 


Field 


4: 


Field 


5: 


Field 


6: 


Field 


7: 


Field 


8: 



15 



16 19 

-Total Length: 22 Bytes- 



Name (8 bytes) — contains only a hexadecimal 1 to ensure that this entry 
is the first entry in the first block of the index. 

Last— block address (3 bytes) — contains the relative track address (TTR) 
of the last block in the volume index. 

HalfMord count (1 byte) — contains a hexadecimal 5 to indicate that 5 
halfMords follow. 

Catalog upper limit (3 bytes) — contains the relative track address (TTR) 
of the last block in the catalog data set. 

Zero field (1 byte) — contains binary zeros. 

Fi rst— avai lable—block address (3 bytes) — contains the relative track 
address (TTR) of the unused block in the catalog that is closest to the 
beginning of the catalog data set. 

Zero field (1 byte) — contains binary zeros. 

Unused (2 bytes) 

Figure 1. The OS CVOL Volume Index Control Entry 
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OS CVOL INDEX CONTROL ENTRY 






Field 1 

X*0000000000000001* 
Name 


Field 2 

TTR of 
last 

block in 
this 
index 


Field 3 

X'03' 
Count 


Field 4 

TTR of 
first 
block in 
this 
index 


Field 5 

Alias 
count 


Field 6 

Unused 
bytes 



11 12 
-Total Length: 18 Bytes- 



15 



16 



This index control entry is similar to a volume index control entry* but it only 
contains information about the index* which it begins. It is 18 bytes long and 
contains six fields. 



Field l: 

Field 2: 
Field 3: 
Field 4: 
Field 5: 



Name (8 bytes) — contains only a hexadecimal 1 to ensure that this entry* 
because it has the louest binary name value* is the first entry in the 
first block of the index. 

Last block address (3 bytes) — contains the relative track address (TTR) 
of the last block assigned to this index. 



HalfMord count (1 byte)- 
halfwords folloM. 



-contains a hexadecimal 3 to indicate that 3 



Index loMer limit (3 bytes) — contains the relative track address (TTR) of 
the block in Mhich this entry appears. 

Number of aliases (1 byte) — contains the binary count of the number of 
aliases assigned to the high—level index. If the index is not a 
high— level index* this field is zero. 



Field e: Unused (2 bytes) 

Figure 2. The OS CVOL Index Control Entry 
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OS CVOL INDEX LINK ENTRY AND INDEX POINTER ENTRY 






Index L 1 nk Entry 



Field 1 

X'FFFFFFFFFFFFFFFF' 
Name 


Field 2 

TTR of next block 
in index (or zero 
if no next block) 


Field 3 

x»oo» 

Count 



11 



-Total Length: 12 Bytes- 



Index Pointer Entry 



Field 1 

Index name (padded to 
right uith blanks if 
necessary) 


Field 2 

TTR of index 


Field 3 

x»oo» 

Count 



11 



-Total Length: 12 Bytes- 



The index link and index pointer entries Qret similar. An index link entry is used 
to chain several blocks of an index together* and an index pointer entry is used to 
chain an index to the next louer— level index. An index link entry is always the 
last entry in any index block. These blocks contain three fields and Qre^ 12 bytes 
long. 



Field l: 



Field 2: 



Name (8 bytes) — contains the name 
points. If the entry is an index 
X'FF FF FF FF FF FF FF FF'. 



of the index to 
link entry, the 



which this entry 
name field contains 






Address (3 bytes) — contains either the relative block address (TTR) of 
the first block of the next level index if it i s an index pointer entry* 
or the relative block address (TTR) of the next block of the same level 
index if it i s an index link entry. 



Field 3: 

Figure 3. The OS CVOL Index Link and Index Pointer Entries 



Halfword count (1 byte) — contains 1 byte of binary zeros to indicate that 
the entry ends here. 



c 
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OS CVOL DATA SET POINTER ENTRY 



Field 1 

Louiest— level name of 
data set or complemented 
generation number 
(if part of GDG) 


Field 2 

DSCB 
TTR or 
zeros 


Field 3 

Count 


Field 4 

Volume 
count 



11 



12 



14 



\ 



Field 5 

Device 
Code 


Field 6 

Serial number 
of volume on 
which data 
set resides 


Field 7 

Data set sequence 
number (zero for 
direct access) 



14 



-/ /- 



18 



24 



Repeated for each volume 
-Total Length: 26 to 74 Bytes- 



The data set pointer entry can appear in any index. It contains the simple name of 
a data set and from one to five 12— byte fields^ each of uthich identifies a volume on 
which the named data set resides. If tjie data set resides on more than five 
volumes, a volume control block pointer entry is substituted for the data set 
pointer entry. A volume control block pointer entry points to a volume control 
block or chain of volume control blocks that point to the volumes that contain the 
data set. 



The data set pointer entry varies in length. The length is determined by the 
formula 14 + 12m, where m is the number of volumes containing the data set. The 
variable m can be from one to five. The data set pointer entry can appear in any 
index, and it contains seven fields. 

Field 1: Name (8 bytes) — contains the simple name of the data set whose volumes 

are identified in field 5. If part of a GDG, these names have the format 
GxxxxVOO, where xxxx is the complement of the GDG number. 

Field 2: DSCB TTR (3 bytes) — contains the track address (TTR) of the data set 
control block if the data set resides on one volume. If the data set 
resides on more than one volume, this field contains binary zeros. 

Field 35 Halfword count (1 byte) — contains the binary count of the number of 

halfwords that follow. The number is found by the formula 6m -t- 1, where 
m is the number of volumes on which the data set resides. The variable m 
can be from one to five. 

Field 45 Volume count (2 bytes) — contains the binary count of the number of 
volumes identified in field 5 of this entry. 

Field 55 Device code (4 bytes) — contains the device code of the device on which 
the volume with the volume serial number in field 6 can be mounted. 

Field 65 Volume serial number (6 bytes) — contains the volume serial number of one 
of the volumes of the data set. 

Field 75 Data set sequence number (2 bytes) — contains the sequence number of the 
data set on a magnetic tape volume. It is zero for any other device 
class. 

Figure 4. The OS CVOL Data Set Pointer Entry 
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OS CVOL VOLUME CONTROL BLOCK POINTER ENTRY 






Field 1 

LoMest level 
of data set 
name 


Field 2 

TTR of 
volume 
control 
block 


Field 3 

X'Ol' 
Count 


Field 4 

X'OOOO' 
Dummy 
data 
entry 



8 11 

-Total Length: i^ Bytes- 



12 



The volume control block pointer entry is used instead of a data set pointer entry 
Mhen the data set resides on more than five volumes. This entry points to a volume 
control blocks Mhich» in turn* describes the data set. The entry is 1^ bytes long. 

Field l: Name (8 bytes) — contains the last name of the qualified name of the data 
set identified by this entry. 

Field 2s Address (3 bytes) — contains the relative block address (TTR) of the 
volume control block identifying the volumes containing the data set 
named in field 1. 

Field 3: HalfMord count (1 byte) — contains a hexadecimal 1 to indicate that 1 
halfword follous. 

Field 4! Zero field (2 bytes) — contains hexadecimal zeros. 

Figure 5. The OS CVOL Volume Control Block Pointer Entry 
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VOLUME CONTROL BLOCK 



Field 1 

Count 


Field 2 

Device 
Code 


Field 3 

Serial 
number 
of volume n 


Field 4 

Data set sequence 
number for the 
volume described 
in field 5. Zero 
for direct access 



m+4 



m+10 



C 



Repeated once for each volume; maximum of 20 



Field 5 

Ten bytes 
of zeros 


Field 6 

TTR of next 
volume control 
block> or zero 
if none 


Field 7 

x»oo» 



242 



252 

-Total Length: 256 Bytes- 



255 



-/ /- 



A volume control block contains the description of all the volumes of a data set 
that resides on more than five volumes. If a data set resides on less than six 
volumes^ a volume control block is not built and the volumes are described in a data 
set pointer entry. One volume control block can describe as many as 20 volumes. 
Volume control blocks may be chained together to catalog a data set residing on more 
than 20 volumes. 

The volume control block is always 256 bytes long» regardless of the number of 
volumes described. 



Field l: 



Fields 2f 3, ^i 



Field 5: 
Field e: 



Volume count (2 bytes) — the first volume control block contains 
the binary count of the total number of volumes on which the data 
set resides. The value of this field is reduced by 20 for each 
subsequent volume control block. 1ft for example* the data set 
resides on 61 volumes* there will be four volume control blocks 
for the data set. The volume count field of each will contain 61» 
41» 21» or 1» respectively. 

Volume identification (12 to 240 bytes) — contains from 1 to 20 
entries* each of which identifies a volume on which the data set 
resides. Each entry contains a 4--byte device code* a 6— byte 
volume serial number* and a 2— byte data set sequence number. The 
data set sequence number is zero for data sets on direct access 
volumes. 

Zero field (10 bytes) — contains binary zeros. 

Chain address (3 bytes) — contains the relative block address (TTR) 
of the next volume control block* if additional blocks are needed 
to describe the data set. If this is the last volume control 
block for the data set* this field will be set to binary zeros. 



Field 72 Zero field (1 byte) — contains binary zeros. 
Figure 6. The OS CVOL Volume Control Block 
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OS CVOL POINTER ENTRY 



Field 1 

Name of index on 
other OS CVOL 


Field 2 

Dummy Pointer 
field? zeros 


Field 3 

X»05' 
Count 



n 



12 



Field 4 

Device code of 
OS CVOL 


Field 5 

Serial number of 
OS CVOL 



12 



16 



-Total Length: 22 Bytes- 



The OS CVOL pointer entry is used to indicate that a particular index 

resides on a volume other than the system residence 

volume. 

OS CVOL pointer entries can exist only in the volume index. 

They are 22 bytes long. 

Field 1' Name (8 bytes) — contains a high— level index name 
that appears in the volume index of the OS CVOL 
identified in fields 4 and 5. 

Field 2! Address (3 bytes)— contains zeros* because this entry 
references no other entry in the 
catalog. 

Field 3: HalfMord count (1 byte) — contains the hexadecimal value 5 to 
indicate that 5 halfMords 
follow. 

Field 4: OS CVOL device code (4 bytes) — contains the 
device code of the specified control 
volume. 

Field 5: OS CVOL serial number (6 bytes) — contains the 

volume serial number of the OS CVOL which has an 

entry in its volume index of the same name as this entry. 






Figure 7. The OS CVOL Pointer Entry 



OS CVOL POINTER ENTRY (OLD) 



Until Release 17 of OS MFT/MVT, the OS CVOL pointer entry was 
the same as the present OS CVOL pointer, except that there was 
no field 4 (device code); the OS CVOL pointer entry was 18 bytes 
long. After Release 17, the OS CVOL pointer entry i s 22 bytes 
long. This is mentioned because some OS CVOLs may still contain 
entries in the old format and the catalog management routines 
may still check for them. 
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OS CVOL GENERATION INDEX POINTER ENTRY 



o 



Field 1 

Namts 


Field 2 

TTR 


Field 3 

Count 


Field 4 

Flags 


Field 5 

Maximum 
Count 


Field 6 

Current 
Count 



11 12 13 

■Total Lengths 16 Bytes- 



1^ 



A generation index pointer entry is the entry that identifies a generation data 
group (GDG). It represents the next to the louiest— level of a group of generation 
data set names. It is created by using the BLDG macro. 

Field 1: Name (8 bytes) — this name represents the GDG level that is next to the 
loMest level of GDG data set names. 

Field 2s Address (3 bytes) — contains the relative track address (TTR) of the first 
block of the level containing the louest— level GDG names. These names 
have the format GxxxxVOO^ Mhere xxxx is a complement of the GDG number. 

Field 3' Count (1 byte) — X'02' identifies this entry and indicates the number of 
halfMords that folloM this field. 

Field 4? Flags (1 byte) — indicates the options specified by the creator of the 
GDG. 

X»02'=DELETE option. 

X'01'=EMPTY option. 



Field 5: 
Field 6: 

Figure 8. The OS CVOL Generation Index Pointer Entry 



Maximum Count (1 byte) — a binary number that specifies the maximum number 
of generations allouied in the generation index at one time. 

Current Count (2 bytes) — the binary count of the number of generations 
currently cataloged in the generation data group (GDG). 
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OS CVOL ALIAS NAME 



.J 



Field 1 

Alias Name 


Field 2 

TTR 
pointer 


Field 3 

Count 


Field 4 

True Name 



11 12 
-Total Length! 20 Bytes- 



An alias entry defines an alternative name for the high— level qualifier of a data 
set name. 



Field l: 
Field 2: 
Field 3: 
Field 4: 

Figure 9. The OS CVOL Alias Name 



Name (8 bytes) — contains the alias of the high— level index whose relative 
track address is found at field 2. 

Address (3 bytes) — contains the relative track address (TTR) of the first 
block of the index named in field 4. 

Count (1 byte) — identifies this entry and contains the binary count of 
the number of halfMords that folloM. The number is X'04*. 

True name (8 bytes) — contains the name of the index whose alias appears 
in field 1. 






o 
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CHAPTER 2. MANAGING THE VOLUME TABLE OF CONTENTS (VTOC) 



The direct access device storage management (DADSM) routines 
control allocation of space on direct access volumes through the 
volume table of contents (VTOC) of that volume^ and through the 
VTOC index if one exists. This chapter gives an overview of the 
VTOC and the VTOC index» and discusses hoM to use systetr macros 
to access the VTOC and VTOC index. 



THE VTOC 



The VTOC is a data set on a direct access volume that describes 
the contents of that volume. It resides in a single extent 
(that is» it is a continuous data set)» anyuihere on the volume 
after cylinder Q, track 0. Its address is located in the 
VOLVTOC field of the standard volume label (see Figure 10). 



Standard Volume Label 



11(B) 

VOLVTOC (10 bytes) 
CCHHR of first 
record in VTOC 



•f^ 







VTOC Data Set 
(Can be located anywhere 
on the volume after 
cylinder 0, track 0.) 



%J 



Figure 10. Locating the Volume Table of Contents (VTOC) 
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The VTOC is composed of 140-byte data set control blocks (DSCBs) 
that correspond either to a data set or VSAM data space 
currently residing on the volume^ or to contiguous^ unassigned 
tracks on the volume. DSCBs for data sets or data spaces 
describe their characteristics and the characteristics of the 
tracks on uihich they reside. DSCBs for contiguous^ unassigned 
tracks indicate their location. 



DATA SET CONTROL BLOCK (DSCB) FORHAT TYPES 



Format-O DSCB 



The VTOC has seven different kinds of DSCBs. This section lists 
the different kinds of DSCBs» Mhat they are used for» houi many 
exist on a volume^ and hoM they are found. 

The first record in every VTOC is the VTOC (format-4) DSCB that 
describes (1) the device that the volume resides on> (2) the 
attributes of the volume itself » and (3) the size and contents 
of the VTOC data set itself. 

The format-4 DSCB is followed by a free-space (format-5) DSCB» 
Mhich for a nonindexed VTOC lists the extents on the volume that 
have not been allocated to a data set or VSAM data space. Each 
format-5 DSCB contains 26 extents. If there are more than 26 
available extents on the volume^ another format-5 DSCB Mill be 
built for ey/ery 26 extents. The format-5 DSCBs are chained 
using the last field of each format-5 DSCB. An indexed VTOC 
does not use format-5 DSCBs for describing free space; however » 
one empty format-5 DSCB is provided to allow a basis for 
converting back to a nonindexed VTOC. 

The third and subsequent DSCBs in the VTOC do not necessarily 
occupy contiguous space* nor do they have any prescribed 
sequence. 

A data set or VSAM data space is defined by one or more DSCBs in /^ ^ 

the VTOC of each volume on which it resides. The number of ^ J 

bSCBs needed to define a data set or VSAM data space is ^---^ 

determined by (1) the organization of the data set (ISAM data 

sets need a format-2 DSCB to describe the index) and (2) the 

number of extents the data set or VSAM data space occupies (a 

format-3 DSCB is needed to describe the 4th through the 16th 

extents; additional format-3 DSCBs may be required to describe 

the extents for a VSAM data set cataloged in an ICF catalog). 

Figure 11 on page 37 shows the general makeup of a VTOC and the 

DSCBs needed to define two types of data sets (ISAM and 

non-ISAM). 

Data set A (in Figure 11 on page 37) i s an ISAM data set; three 
DSCBs* a format-l» format-2, and format-3» ar& required. Data 
sets B» C* and D could be sequential, partitioned, or direct 
data sets or VSAM data spaces. Data set B has more than three 
extents and therefore requires both a format-1 and a format-3 
DSCB. 

Data sets C and D have three or fewer extents and need only a 
format-1 DSCB. The format-6 DSCB, pointed to by the format-4 
DSCB, is used to keep track of the extents allocated in order to 
be shared by two or more data sets (split-cylinder data sets). 
For example, if data sets C and D share an extent made up of one 
or more cylinders, this extent would be described in the 
format-6 DSCB. Note that split-cylinder data sets cannot be 
allocated, but existing split-cylinder data sets can still be 
processed. 



NAME! Free VTOC Record 

FUNCTION: The unused records in the VTOC, which contains 140 
bytes of binary zeros. To delete a DSCB from the VTOC, a 
format-0 DSCB is written over it. 
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o 



HOU MANY: One for every unused 140-byte record on the VTOC. The 

DS^DSREC field of the format-4 DSCB is a count of the number of 

format-0 DSCBs on the VTOC. This field is not maintained for an 
indexed VTOC. 

HOU FOUND: Search on key equal to X*00' (sometimes X*00000000«) 
for a nonindexed VTOC; for an indexed VTOC, the VTOC map of 
DSCBs is used to find a format-0 DSCB. 



Format'l DSCB 



Forma t-2 DSCB 



f^^ 

^L^' 



Format-3 DSCB 



NAME: Identifier 

FUNCTION: Describes the first three extents of a data set or 
VSAM data space. 

HOU MANY: One for every data set or data space on the volume, 
except the VTOC. 

HOU FOUND: Search on key equal to the data set name. For an 
indexed VTOC, a CCHHR pointer for each data set name is in the 
VTOC index. 



NAME: Index 

FUNCTION: Describes the indexes of an ISAM data set. 

HOU MANY: One for every ISAM data set (for a multivolume ISAM 
data set, a format-2 DSCB exists only on the first volume). 

HOU FOUND: Chained from a format-1 DSCB that represents the data 
set. 



NAME: Extension 

FUNCTION: Describes the 4th through 16th extents of a data set 
or VSAM data space. Data sets and VSAM data spaces are 
restricted to 16 extents per volume. VSAM data sets cataloged 
in an ICF catalog may be extended to a maximum of 123 extents, 
in Mhich case there may be up to ten format-3 DSCBs. 

HOU MANY: One for each data set or VSAM data space on the volume 
that has more than three extents. There may be up to ten for a 
VSAM data set cataloged in an ICF catalog. 

HOU FOUND: Chained from a format-2 or a format-1 DSCB that 
represents the data set or VSAM data space. In the case of a 
VSAM data set cataloged in an ICF catalog, the chain may be from 
a preceding format-3 DSCB. 



Format-4 DSCB 



NAME: VTOC 

FUNCTION: Describes the extent and contents of the VTOC and 
provides volume and device characteristics. If the VTOC is 
indexed, certain fields of this DSCB are not maintained by 
DADSM. See "Structure of an Indexed VTOC." 

HOU MANY: One on each volume. 

HOU FOUND: VOLVTOC field of the standard volume label contains 
its address. It is always the first record in the VTOC. 
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Format -5 DSCB 



NAME: Free Space 

FUNCTION: On a nonindexed VTOC* describes the space on a volume 
that has not been allocated to a data set or to a VSAN data 
space (available space). For an indexed VTOC» format-5 is zero* 
and the volume pack space map describes the available space. 

ROM MANY: One for every 26 non-contiguous extents of available 
space on the volume for a nonindexed VTOC; for an indexed VTOC> 
there is only one. 

HOU FOUND: The first format-5 DSCB on the volume is always the 
second DSCB of the VTOC. If there is more than one format-5 
DSCB» it Mill be chained from the previous format-5 DSCB via the 
DS5PTRDS field of each format-5 DSCB. 






Format-6 DSCB 



NAME: Shared Extent 

FUNCTION: Describes the extents shared by two or more data sets 
(split-cylinder extents). 

HOM MANY: One for every 26 split-cylinder extents on the VTOC. 

HOW FOUND: The address of the first format-6 DSCB is contained 
in the DS4F6PTR field of the format-4 DSCB. If there is more 
than one format-6 DSCB on the volume* it Mill be chained from 
the previous format-6 DSCB via the DS6PTRDS field of the 
format-6 DSCB. 



ALLOCATING AND RELEASING SPACE 



The DADSM allocate and extend routines assign tracks and 
cylinders on direct access volumes for neN data sets and VSAN 
data spaces. The DADSM extend routine obtains additional space 
for a data set or VSAM data space that has already exceeded its 
original* primary allocation. The DADSM scratch and partial 
release routines are used to release space that is no longer 
needed on a direct access volume. 

The DADSM routines allocate and release space by adding* 
deleting* and modifying the DSCBs. Uhen space is needed on a 
volume* the allocate routines search the appropriate DSCBs for 
enough contiguous* available tracks to satisfy the request. If 
there are not enough contiguous tracks* the request is filled 
using as many as five noncontiguous groups of free tracks. The 
appropriate DSCBs are modified to reflect the assignment of the 
tracks. 

klhen space is released* the scratch routines free the DSCBs of 
the deleted data set or data space. For a nonindexed VTOC* to 
indicate that the tracks containing the affected data set or 
data space can be reallocated* a free space (format-5) DSCB is 
built* or modified if existent. For an indexed VTOC* the index 
i s updated. 






THE VTOC INDEX 



The VTOC i ndex i s a physical-sequential data set* residing on 
the same volume as the VTOC. It contains an index of data set 
names of Format-1 DSCBs in the VTOC* as Mell as free space 
information. The index is searched instead of the hardMare keys. 

The VTOC index is optional. It can be built over an existing 
VTOC and inactivated so that the VTOC is processed Mithout using 
the index. 
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Standard Volume Label 




Data Set A 



Data Set B 



Fornut-4 DSCB 

Description of 
device, volume, 
and the VTOC 
extent 



First FS DSCB 

Description of 
26 available 
extents 




rF6rmat-2pSCU 
lescription of ^ 




Format-l DSCB 
Description of 
the data set and 
its first 3 extents" 




Data Set C 



Format-6 DSCB 

Description of 
as many as 26 
shared-cylinder 
extents 



Next lonnat-i UiiLB '^ lormat-3 DSCB -^ ^ I 
DescriDtion of "^ Desftrintinn nf ^ . I 



Description of 
as many as 26 
available extents 



Format-3 DSCB 

Description of 
the 4th- 16th 
extents of 
data set B 



.Format- 1 DSCB - 

, Description of • 
■ data set C and its] 
\ first 3 extents 



Data Set D 



wmmm^^mm 



fFormat-3 DSCBi 
description of 
[the 4th- 16th 
fextents of 
: data set A 



Format-l DSCB 

k* Description of ^ 

l^the data set and ^ 

I /'its first 3 extents^" 



-^h 



-T>^ 



' J "ntj " ■' ■" V""" 




DSCB for an ISAM data 
set (Data Set A) 




DSCB for a 
non-ISAM data 
set (Data Sets B, C, D) 
or a VSAM data space 



Note: Empty boxes in the VTOC data set represent free VTOC Records (Format-0 DSCBs) 
Figure 11. Contents of 'VTOC — DSCBs Describing Data Sets 



Each VTOC index is formatted by Device Support Facilities with 
physical blocks 2048 bytes in length. These physical blocks are 
the VTOC index records (VIRs)» the basic structural units of the 
index. The kind of information they contain depends on the part 
of the index they belong to. 
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Several different kinds of records* each built from one or more 
VIRs* are in a VTOC index: 

• The VTOC index entry record (VIER)» Mhich is used to access 
format-1 DSCBs and the format-4 DSCB 

• The VTOC pack space map (VPSM)> Mhich shoMS Mhat space has 
been allocated on a disk pack 

• The VTOC index map (VIXM)» Mhich shoMs Mhich VIRs have been 
allocated in the VTOC index 

• The VTOC map of DSCBs (VMDS), Mhich shoMS Mhich DSCBs have 
been allocated in the VTOC 



AN EXAMPLE OF A VTOC AND ITS INDEX 



A format-1 DSCB in the VTOC contains the name and extent 
information of the VTOC index. The name of the index must be 
*SYS1 . VTOCIX.xxxxxxxx' » Mhere *xxxxxxxx' can be anything valid 
in a data set name and is generally the serial number of the 
volume containing the VTOC and its index. The name must be 
unique Mi thin the system to avoid ENQ contention. The 
relationship of a VTOC to its index is shoMn in Figure 12. Each 
of the components of the index is discussed separately in the 
folloMing sections. 



VTOC 



VTOC Index 



Format-^ DSCB 






Format~5 DSCB 




Other DSCBs 




Format-1 DSCB for the VTOC 
Index: SYSl . VTOCIX.nnn 








Other DSCBs 





VIXM 



VPSM 



VMDS 



VIER 



VIER 



VIER 



.4' V\ 
\1 to' 



Figure 12. Relationship of a VTOC to Its Index 



THE VTOC INDEX ENTRY RECORD (VIER) 



VIERs have these characteristics: 

• A VIER uses one VIR and contains variable-length index 
entries. The number of VIERs in an index is variable* 
depending on the number of data sets on the volume. 

• VIERs in a VTOC index may be on one or many levels. All 
index entries in a VIER are at the same index level. VIERs 
have a hierarchic relationship. Index entries in 
higher-level VIERs point to loMer-level VIERs. Index 
entries in level-one VIERs (those at the loMest level) point 
to format-1 DSCBs for data sets on the volume. 

• A higher-level VIER is created Mhen the fourth loMer-level 
VIER is created. Uhen that neH higher-level VIER is filled 
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Mith pointers to loMer-level VIERs» a new VIER at the same 
level is created. Again» Mhen the fourth VIER at the same 
level is created* a VIER at a still higher level is created* 
adding another level to the index. 



Contents of VIER Fields 



Each VIER contains a header and sections (see Figure 13). The 
VIER header contains! 

A field identifying the VTOC index record as a VIER. 

The relative byte address CRBA) of the VIER. 

A pointer to a VIER at the same level (hence* a "horizontal" 
pointer). The VIER pointed to contains index entries Mhose 
keys are greater than any key in the pointing VIER. 

The level number (LVD of this VIER. 

The number (SECNO) of sections (a VIER contains eight 
sections) . 

The length (SECL) of the sections (each section is 246 bytes 
in length). 

The offsets to the first-used and the last-used sections. 

The 44-byte high key of the VIER. 

Each section contains* 

An offset to the last entry in the section (or zero if the 
section is empty) 

Index entries 



0(00) 
4(04) 
8(08) 
12(0C) 
16(10) 
20(14) 
24(18) 
28(1C) 
32(20) 
76(4C) 



EBCDIC Characters "VIER" 



RBA of This VIER 



Horizontal Pointer 



Old Horizontal Pointer 



LVL 



PTRL 



FLGl 



SECNO 



Reserved 



SECL 



Offset to First— Used Section 



Offset to Last-Used Section 



Highest Key in This VIER 



Section 1 



Section 8 



Index 
Header 



8 Sections 
Containing 
Index Entries 



Figure 13. Format of the VTOC Index Entry Record (VIER) 
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Format of a VTOC index Entry 

The format of an index entry iss 



FLG 


KEYL 


Unused 


Record Pointer 


Key 



Name Offset Bytes Description 

VXEFLG 00(00) 1 Flag byte 

VXEKEYL 01(01) 1 Length of the VXEKEY field 

VXEFC 02(02) 1 Unused 

VXERPTR 03(03) 4 or 5 Record pointer 

VXEKEY 07(07) 1 to 44 Name of a data set» if a 

or level— one VIER; if not» the 

08(08) high key in the header of a 

lower—level VIER 



o 



> 



Each index entry contains^ 

• A flag byte. 

• A keylength field (which contains a value of 1 to 44» 
depending on the length of the data set name). 

• A record pointer (VXERPTR) that is one of the following: 

- In level-one VIERs, the 5-byte CCHHR of the format-1 or 
format-4 DSCB that represents the data set whose name is 
the key in the entry 

In other VIERs, the 4-byte RBA of the lower-level VIER 
whose high key is the key in the entry 

• A key which for level 1 VIERS is the data set name» and for 
level 2 or higher VIERs is the high key of a lower-level 
VIER. Trailing blanks are suppressed in the VTOC index 
entry. 



,4' >\ 



Uhen a VIER Is Created 



The first level-one VIER is created when the VTOC index is 
created. Subsequent VIERs are created when a data set name is 
to be added to the VTOC index but the VIER to which it should be 
added is full. A new VIER is created in the following manner^ 

• A new VIER is allocated. 

• Half of the sections from a full VIER (those containing the 
highest keys) are moved into the new VIER» leaving each VIER 
half empty. 

• The new index entry is added to one of the two VIERs> 
depending on its key. 



A Tree of Linked VIERs 



Figure 14 on page 41 shows how VIERS are related to each other, 
Note that the VIERs (which are simplified here — only the high 
key is shown in the header) form a type of "tree structure." 



HOW a Format-1 DSCB Is Found 



In the search for the format-1 DSCB for a particular data set» 
one path along the tree structure is followed. 

As seen in Figure 13 on page 39> a field in the header of a VIER 
contains the highest key of any index entry in that VIER. 



o 
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Beginning with this field in the first high-level VIER» the 
folloMing search logic is used^ Is the key of the data set (the 
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J 



High Key ■ 



Entries 



VIER 



M32107.LIB 



B41103.TEST 
M32107.LIB 



VIER 



B41103.TEST 



44X'04' 

A11307.CLIST 

B0102.DATA 



VIER 



M32107.LIB 



C0102.ASM 
M32107.LIB 



Format-1 DSCBs 
in the VTOC 



VIER 



44X'FF' 



SYS1.MACLIB 
44X'FF' 



VIER 



SYS1.MACLIB 



Level-2 
ViERs 



VIER 



44X'FF' 



SYS1.VT0CIX.A 

X.Y.Z. 

44X'FF' 



Level-1 
^ VIERs 



Dummy Last 
Entry in 
VTOC Index 



Format-4 DSCB in the VTOC 



Figure 14. Structure of Linked VIERs 



data set name) loMer than or equal to the VIER's high key? If 
neither* the test is again applied Mith the VIER having a 
greater high key pointed to by the horizontal pointer. This 
procedure continues until a VIER is found having a high key that 
is greater than or equal to the key of the data set. 
Comparisons are then made with the entries in the VIER*s 
sections. Eventually* an entry is found Mith a key greater than 
or equal to the data set key. This entry points to a VIER at 
the next-lower level. 

The search proceeds to successively lower levels until an entry 
in a level-tMo VIER is found whose key is greater than or equal 
to the key of the data set. This entry points to a level-one 
VIER that* in turn* contains an entry with a key that is equal 
to the data set key and that points to the format-1 DSCB for the 
desired data set. 



Special cases In the Search for a DSCB 



If there is only one level in the VTOC index* the entries in the 
VIERs all point to format-1 DSCBs* so only one level need be 
searched. 

If an update to the VTOC index requires a new VIER and the 
update is interrupted (for example* because of an I/O error or a 
system failure)* the entry in the level-n VIER may contain a key 
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that is greater than the high key in the lower-level VIER 

pointed to by that entry. In this case> two VIERs at level n-l ^^ 

may have to be searched. This situation is corrected when DADSM (f \ 

next processes the volume. '\^ 



THE VTOC PACK SPACE HAP (VPSH) 



The VPSH accounts for space on a disk pack. It shows what space 
on the volume has been allocated and what space remains free. 

The map contains bit maps of the cylinders and tracks on the 
volume. A value of one indicates that the cylinder or track has 
been allocated; a value of zero, that it has not been allocated. 
The bit representing a cylinder is set to zero if no tracks on 
the cylinder have been allocated; it is set to one if any track 
has been allocated. Tracks assigned as alternate tracks are 
marked as allocated. 

The VPSH replaces the chain of format-5 DSCBs» but one empty 
format-5 DSCB is left in the VTOC to allow for conversion back 
to a nonindexed VTOC, a process that requires reconstruction of 
a format-5 DSCB chain. 

The format of an index map (including the VPSH) is shown in 
Figure 15. 



00(00) 
04(04) 
08(08) 
12(0C) 
16(10) 
20(14) 
24(18) 
28(1C) 
32(20) 
36(24) 
40(28) 



ID of This Map 



RBA of This Map 



Hori^zontal Pointer to Next VIR 



Sequence Number o! First Entry 



VRFDA 



FLGl LUFl 



VRFO 



LUOF 



Size of Large Unit Map 



SUFI SUBIT 



SUOF 



Size of Small Unit Map 



Reserved 



VIR 



RBA of First High-level VIER 



Large Unit Map 
(VTOC Pack Space Map Only) 



Small Unit Map 



VTOC Recording Facility Data 
(VTOC Index Map Only) 






Figure 15. An Index Map 



THE VTOC ZHDEX HAP (VXXH) 



The VIXM contains a bit map in which each bit represents one 
VTOC index record (VIR). The status of the bit indicates 
whether the VIR is allocated (1) or unallocated (0). 
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An area of the VIXM is reserved for VTOC recording facility 
(VRF) data. (This is the facility that allows detection of and 
recovery from certain errors in an indexed VTOC.) 

A field in the first VIXM record points to the first high-level 
VIER. Another field in the first VIXM record (VIR in Figure 16) 
contains the number of VTOC index records uihich contain all the 
space maps. 



THE VTOC MAP OF DSCBS (VMDS) 



The VMDS contains 
DSCB in the VTOC. 
DSCB is allocated 



a bit map in which 

The status of the 

(1) or unallocated 



each bit represents one 
bit indicates whether the 
(0), 



#*>, 



Name 



Offset 



Bytes 



VIMAP 

VIMH 

VIMID 


00(00) 
00(00) 
00(00) 


2048 

44 

4 


VIMRBA 
VIMHZPTR 


04(04) 
08(08) 


4 
4 


VIMORG 


12(0C) 


4 


VIMVRFDA 


16(10) 


2 



VIMVRFO 


18(12) 


2 


VIMFLGl 
VIMVRFSW 


20(14) 


1 

1 


VIMLUFl 
VIMLUOF 


21(15) 
22(16) 


.XXX xxxx 

1 

2 


VIMLUSZ 
VIMSUFl 
VIMSUBIT 


24(18) 
28(1C) 
29(1D) 


4 
1 
1 


VIMSUOF 


30(1E) 


2 


VIMSUSZ 

VIMVIR 
VIMFHLV 


32(20) 
36(24) 
39(27) 
40(28) 


4 
3 
1 
4 


VIMLUMAP 


44(2C) 


kk 


VIMSUMAP 


mm 


nn 


VIMVRF 


PP 


qq 


Figure 16. 


The Format 


of a VTOC 



Description 

VTOC map 

VTOC map header 

Map ID in EBCDIC 



(»VPSM' 



or 



•VMDS') 
map 



'VIXM' 

RBA of this 

Horizontal RBA pointer to 

next VIR of this map 

Sequence number of the 

first entry in the map 

Offset to current VRF data 

(if VIMVRFSW=1) or offset 

where VRF data may be 

written (if VII1VRFSW=0), 

(first VIXM only) 

Offset to VRF area (first 

VIXM VIR only) 

Flag byte 

VRF data exists if 1 

Reserved 

Large unit flag byte 

Offset into VIR of large 

unit map (zero if none) 

Size in bits of large unit map 

Small unit flag byte 

Number of small unit bits per 

large unit (zero if none) 

Offset into VIR of small unit 

map 

Size in bits of small unit map 

Reserved 

Number of map records (VIXM only) 

RBA of first high-level VIER 

(VIXM only) 

Large unit map (kk is VIMLUSZ/8, 

rounded up) 

Small unit map (mm is VIMSUOF> nn 

is VIMSUSZ/8, rounded up) 

VRF area (pp is VIMVRFO, qq is 

remainder of first VIXM) 



STRUCTURE OF AN INDEXED VTOC 



An indexed VTOC is identical to a nonindexed VTOC, except that 
for an indexed VTOC only a single format-5 DSCB exists and is 
empty, and certain format-4 DSCB data (the number of format-0 
DSCBs and the CCHHR of the highest format-1 DSCB) is not 
maintained by DADSM. The DOS bit (bit in field DS4VT0CI), set 
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to one in the format-^ DSCB» indicates that these fields (as 
well as the format-5 DSCB) cannot be relied on. The index bit 
(bit 7 in field DS4VT0CI) is set in the format-4 DSCB; it 
indicates that a VTOC index exists. 



SCRATCH/RENANE/ALLOCATE RESTRICTIONS 



A VTOC index data set may not be scratched if the VTOC index is 
active. Neither may a VTOC index data set be renamed if the 
VTOC index is active* unless it is being renamed to another name 
beginning uiith *SYS1. VTOCIX. * . A data set may not be renamed to 
a name beginning Mith 'SYSl. VTOCIX. ' if there is already such a 
data set on the volume. Only one data set whose name begins 
with *SYS1. VTOCIX. ' may be allocated on a volume. 



CREATING THE VTOC AND VTOC INDEX 



To prepare a volume for use (to initialize it)» the Device 
Support Facilities utility is used. One of the things this 
utility does i s to build the VTOC. After ini tialization» this 
VTOC will contain a format-^ DSCB and a format-5 DSCB. For a 
nonindexed VTOC, the format-5 DSCB contains an extent entry for 
all the free space on the volume; the initial number of extents 
in the format-5 DSCB is one or two, depending on where the VTOC 
is located on the volume. If the VTOC is located somewhere 
other than at the beginning or end of the volume, two extent 
entries are needed to describe the free space that precedes and 
follows it. For an indexed VTOC, the format-5 DSCB contains a 
zero. 

A VTOC index can be created when a volume is initialized by 
using the Device Support Facilities command INIT and specifying 
the INDEX key word. 

A nonindexed VTOC can be converted to an indexed VTOC by using (^ \ 
the command BUILDIX and specifying the IXVTOC keyword. The \„/ 
reverse is also possible by using the BUILDIX command and 
specifying the OSVTOC keyword. 

For more detailed information, refer to Device Support 
Facilities User's Guide and Reference. 



PROTECTING A VTOC AND VTOC INDEX 



RESOURCE ACCESS CONTROL FACILITY (RACF) 



You can protect the VTOC and VTOC index by using the Resource 
Access Control Facility (RACF). This is done by defining the 
volume serial entity under the RACF class DASDVOL. A user must 
be authorized to the DASDVOL/volume serial entity at the 
following levels^ 

• At the UPDATE level, to open the VTOC for output processing 

• At the UPDATE level, to open for output processing any data 
set whose name begins with *SYS1. VTOCIX. * 

• At the ALTER level, to allocate, rename, or scratch any data 
set whose name begins with 'SYSl. VTOCIX. ' 

• At the ALTER level, to rename a data set to any name that 
begins with 'SYSl .VTOCIX. • 

Neither the VTOC nor the VTOC index is protected from being 
opened for input processing by the DASDVOL/volume serial entity. 

Note that neither the VTOC nor the VTOC index can be protected 
through the RACF class DATASET. 
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AUTHORIZED PROGRAM FACILITY (APF) REQUIREMENTS 



O 



PASSUORD PROTECTION 



A program must be authorized by the authorized program facility 
(APF) to perform any of the folloMing functions^ 

• Opening a VTOC for output processing 

• Opening for output processing a data set Mhose name begins 
Nith •SYSl.VTOCIX.' 

• Allocating* renaming* or scratching any data set whose name 
begins with 'SYSl. VTOCIX. ' 

• Renaming a data set to any name that begins with 
'SYSl.VTOCIX.' 



The VTOC index data set may be password protected. The 
protection is the same as for any password-protected data set, 
Password checking is bypassed if the volume on which the VTOC 
index resides is protected by RACF through the DASDVOL class. 



COPY/RESTORE/INITIALIZE REQUIREMENTS 



OPERATIONS ON VOLUMES CONTAINING AN UNINDEXED VTOC 






Restoring a Volume from a Dump Tape . There are no 
operational requirements if you change the volume serial 
number or do a partial restore that does not modify the 
VTOC. If you do a restore dnd change the VTOC size without 
changing the volume serial number* the volume must be varied 
offline after it is restored. You should not do a restore 
on a volume with an indexed VTOC. 

Copying a Volume . There are no operational requirements if 
you change the volume serial number or do not modify the 
VTOC of the receiving volume. If you do a copy and change 
the VTOC size without changing the volume serial number* the 
volume must be varied offline after it is copied. You 
should not do a copy from a volume with an indexed VTOC. 



OPERATIONS ON VOLUMES CONTAINING AN INDEXED VTOC 



You should use Device Support Facilities to convert a VTOC to a 
nonindexed format to update the volume. If you do not* take 
note of the following information? 

• Initializing a Volume . If you do not change the volume 
serial number* the volume should be varied offline before 
starting the job. 

• Restoring a Volume from a Dump Tape . There are no 
operational requirements if you change the volume serial 
number or do a partial restore that does not modify the VTOC 
or VTOC index. If you do a restore and modify the VTOC or 
VTOC index without changing the volume serial number* the 
volume should be varied offline after it is restored. 

• Copying a Volume . There are no operational requirements if 
you change the volume serial number of the receiving volume 
or do a partial dump without modifying the VTOC or VTOC 
index. If you modify the VTOC or VTOC index without 
changing the volume serial number* the receiving volume 
should be varied offline after it is copied. 

• Shared DASD Considerations . In shared DASD environments* 
whenever the VTOC index is modified or relocated* or the 
volume is changed from indexed VTOC to OS VTOC* or from OS 
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VTOC to indexed VTOC, the device should be varied offline to 
the sharing system or systems. 



USING THE OBTAIN, SCRATCH, AND RENAME HACROS 



This section tells how to use the OBTAIN, SCRATCH, and RENAME 
macro instructions. These macros are most commonly used by the 
operating system and the data set utility programs (lEHMOVE, 
lEBCOPY, and lEHPROGM), but you may use them in your own 
routines. The functions you can perform with these macros are? 

• Reading a data set control block from the VTOC — OBTAIN 

• Deleting a data set — SCRATCH 

• Changing the name of a data set — RENAME 

You can read a data set control block (DSCB) into virtual 
storage by using the OBTAIN and CAMLST macro instructions. 
There are two ways to specify the DSCB that you want to readi by 
using the name of the data set associated with the DSCB, or by 
using the absolute track address of the DSCB. You must provide 
a 140-byte data area in virtual storage, into which the DSCB 
will be read. Uhen you specify the name of the data set, an 
identifier (format-1 or format-4) DSCB is read into virtual 
storage. To read a DSCB other than a format-1 or a format-4 
DSCB, you must specify an absolute track address (see "Example** 
on page 48). (DSCB formats and field descriptions are contained 
in Debugging Handbook . ) 

You can delete a non-VSAM data set by using the SCRATCH and 
CAMLST macro instructions. This causes the DSCBs for the data 
set to be deleted. 

You can change a data set name by using the RENAME and CAMLST 
macro instructions. This causes the data set name in the 
format-1 DSCB for the data set to be replaced with the new name. 






Accompanying the 
coding examples, 
descriptions. 



descriptions of the macro instructions are 
programming notes, and exception return code 



Note: OBTAIN, SCRATCH, and RENAME macro 
used with a SYSIN or SYSOUT data set. 



instructions cannot be 



READING A DSCB BY NAME (OBTAIN AND CAMLST SEARCH): If you 
specify a data set name using OBTAIN and the CAMLST SEARCH 
option, the 96-byte data portion of the identifier (format-1) 
DSCB and the absolute track address of the DSCB are read into 
virtual storage. The absolute track address is a 5-byte field 
in the form CCHHR. The absolute track address field will 
contain zeros for VSAM and VIO data sets. 

The format is^ 



[ symbol ] 
li stname 



OBTAIN 
CAMLST 



1 i stname-addrx 
SEARCH 

y dsname-relexp 
> vol-relexp 
> wkarea-relexp 



1 i stname-addrx 

points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 

SEARCH 

this operand must be coded as shown. 
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dsnatne-relexp 

specifies the virtual storage location of a fully qualified 
data set name. The area that contains the name must be 44 
bytes long. 

Note: A DSNAME of 44 bytes of X'04' (X'040404. . . 04* ) can 
be used to read a format-4 DSCB. 

vol-relexp 

specifies the virtual storage location of the 6-byte volume 
serial number of the volume on uihich the DSCB is located. 

wkarea-relexp 

specifies the virtual storage location of a 140-byte Mork 
area that you must define. 

Example: In the follouiing example* the identifier (format-1) 
DSCB for data set A.B.C is read into virtual storage using the 
SEARCH option. The serial number of the volume containing the 
DSCB is 770655. 



OBTAIN DSCBABC READ DSCB FOR DATA 

X SET A.B.C INTO DATA 

^ AREA NAMED UORKAREA 

Check Return Codes 

DSCBABC CAMLST SEARCH, DSABC,VOLNUM,WORKAREA 

DSABC DC CL44»A.B.C» DATA SET NAME 

VOLNUM DC CL6»770655» VOLUME SERIAL NUMBER 

UORKAREA DS 140C 140-BYTE WORK AREA 



The OBTAIN macro instruction points to the CAMLST macro 
instruction. SEARCH, the first operand of CAMLST, specifies 
that a DSCB be read into virtual storage, using the data set 
name you have supplied at the address indicated in the second 
operand. DSABC, the second operand, specifies the virtual 
storage location of a 44-byte area into which you have placed 
the fully qualified name of the data set Mhose format-1 DSCB is 
to be read. VOLNUM, the third operand, specifies the virtual 
storage location of a 6-byte area into which you have placed the 
serial number of the volume containing the required DSCB. 
UtORKAREA, the fourth operand, specifies the virtual storage 
location of a 140-byte work area into which the DSCB is to be 
returned. 

Control will be returned to your program at the next executable 
instruction following the OBTAIN macro instruction. If the DSCB 
has been successfully read into your work area, register 15 will 
contain zeros. Otherwise, register 15 will contain one of the 
following return codes: 

Code Meaning 

4(04) The required volume was not mounted. 

8(08) The format-1 DSCB was not found in the VTOC of the 
specified volume. 

12(0C) A permanent I/O error was encountered, or an invalid 
format-1 DSCB was found when processing the specified 
volume, or an unexpected error return code was received 
from CVAF (Common VTOC Access Facility). 

16(10) Invalid work area pointer. 

After execution of these macro instructions, the first 96 bytes 
of the work area contain the data portion of the identifier 
(format-l or format-4) DSCB; the next 5 bytes contain the 
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absolute track address (CCHHR) of the DSCB. 
contain zeros for VSAM or VIO data sets. 



These 5 bytes Mill 



READING A DSCB BY ACTUAL DEVICE ADDRESS (OBTAIN AND CANLST 
SEEK): You can read any DSCB from a VTOC using OBTAIN and the 
CAMLST SEEK option. You specify the SEEK option by coding SEEK 
as the first operand of the CAMLST macro and by providing the 
absolute device address of the DSCB you want to read» unless the 
DSCB is for a VIO data set. Only the SEARCH option can be used 
to read the DSCB of a VIO data set. 

The format is^ 



[symbol] 
li stname 


OBTAIN 
CAMLST 


1 i stname-addrx 
SEEK 

fcchhr-relexp 
f vol-relexp 
,wkarea-relexp 



1 i stname-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 



SEEK 



this operand must be coded as shown 



cchhr-relexp 

specifies the virtual storage location of the 5-byte 
absolute device address (CCHHR) of a DSCB. 

vol-relexp 

specifies the virtual storage location of the 6-byte volume 
serial number of the volume on which the DSCB is located. 

wkarea-relexp 

specifies the virtual storage location of a 1^0-byte work 
area that you must define. 

Example: in the following example^ the DSCB at actual-device 
address X*00 00 00 01 07* is returned in the virtual storage 
location READAREA» using the SEEK option. The DSCB resides on 
the volume with the volume serial number 108745. 






OBTAIN ACTADDR 



Check Return Codes 



READ DSCB FROM 
LOCATION SHOWN IN CCHHR 
INTO STORAGE AT LOCATION 
NAMED READAREA 



ACTADDR CAMLST SEEK, CCHHR, VOLSER, READAREA 

CCHHR DC XL5'0000000107' ABSOLUTE TRACK ADDRESS 

VOLSER DC CL6» 108745* VOLUME SERIAL NUMBER 

READAREA DS 140C 140-BYTE blORK AREA 



The OBTAIN macro points to the CAMLST macro. SEEK, the first 
operand of CAMLST, specifies that a DSCB be read into virtual 
storage. CCHHR, the second operand, specifies the storage 
location that contains the 5-byte actual-device address of the 
DSCB. VOLSER, the third operand, specifies the storage location 
that contains the volume serial number of the volume on which 
the DSCB resides. The fourth operand, READAREA, specifies the 
storage location to which the 140-byte DSCB is to be returned. 

Control will be returned to your program at the next executable 
instruction following the OBTAIN macro instruction. If the DSCB 
has been successfully read into your work area, register 15 will 
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contain zeros. OtherMise^ register 15 Mill contain one of the 
folloMing return codes* 

Code Meaning 

4(04) The required volume Mas not mounted. 

8(08) The format-1 DSCB Mas not found in the VTOC of the 
specified volume. 

12(0C) A permanent I/O error Mas encountered or an unexpected 
error return code Mas received from CVAF. 

16(10) Invalid Mork area pointer. 

20(14) The SEEK option Mas specified and the absolute track 
address (CCHH) is not Mi thin the boundaries of the 
VTOC. 

DELETING A DATA SET (SCRATCH AND CANLST SCRATCH): You delete a 
non-VSAM data set by using the SCRATCH and CAMLST macro 
instructions. This causes all data set control blocks (DSCBs) 
for the data set to be deleted^ and all space occupied by the 
data set to be made available for reallocation. If you Mant to 
scratch a data set being processed using virtual input/output 
(VlO)f the data set must have been allocated for use by your 
job. Scratching VIO data sets not allocated to your job is not 
alloMed. 

If the data set to be deleted is sharing one or more cylinders 
Mith one or more data sets (a split-cylinder data set)> the 
space Mill not be made available for reallocation until all data 
sets on the shared cylinders are deleted. 

A data set cannot be deleted if the expiration date in the 
identifier (format-1) DSCB has not passed* unless you choose to 
ignore the expiration date. You specify that the expiration 
date is to be ignored by using the OVRD option in the CAMLST 
macro instruction. 

For information on RACF-defined data sets» see Resource Access 
Control Facility (RACF): General Information Manual . You may 
only scratch a RACF-defined data set (that is, the DSCB 
indicates RACF-defined) if you have alter access authority to 
either the data set/volume serial in the DATASET class, or to 
the volume serial in the DASDVOL class (if the volume is 
RACF-defined). 

If a data set to be deleted is stored on more than one volume, 
either a device must be available on Mhich to mount the volumes, 
or at least one volume must be mounted. In addition, all other 
required volumes must be serially mountable. 

Uhen deleting a data set, you must build a volume list in 
virtual storage. This volume list consists of an entry for each 
volume on Mhich the data set resides. The first tMo bytes of 
the list indicate the number of entries in the list. Each 
12-byte entry consists of a 4-byte device code, a 6-byte volume 
serial number, and a 2-byte scratch status code Mhich should be 
initialized to zero. Device codes are presented in Debugging 
Handbook in the description of UCBTYP. 

If the space to be deleted is a VSAM data space, you must use 
the DELETE command provided by access method services. For 
complete information about the DELETE command, see Access Method 
Services Reference . 

Volumes are processed in the order that they appear in the 
volume list. The volume at the beginning of the list is 
processed first. If a volume is not mounted, a message is 
issued to the operator requesting a volume be mounted. (A 
volume mount message Mill not be issued for a mass storage 
system (MSS) virtual volume; hoMever, a status code Mill be 
returned to your program.) This is only done if register has 
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been loaded with the UCB associated Mith the device on Mhich 
unmounted volumes are to be mounted. (The device must be 
allocated to your job.) If you do not load register with a 
UCB address* its contents must be zero* and at least one of the 
volumes in the volume list must be mounted before the SCRATCH 
macro instruction is issued. 

If the requested volume cannot be mounted* the operator issues a 
reply indicating that the request cannot be fulfilled. A status 
code is then set in the last byte of the volume pointer (the 
second byte of the scratch. status code) for the unavailable 
volume* and the next volume indicated in the volume list is 
processed. 

The format \s' 






[symbol] 
1 i stname 


SCRATCH 
CAMLST 


li stname-addrx 

SCRATCH 

t dsname-relexp 

»fVol list-relexp 

[f >OVRD] 



li stname-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 



SCRATCH 

this operand must be coded as shown. 

dsname-relexp 

specifies the virtual storage location of a fully qualified 
data set name. The area that contains the name must be 44 
bytes long. Xhe name must be defined by a C-type define 
constant (DC) instruction. 

vol list-relexp 

specifies the virtual storage location of an area that 
contains a volume list. The area must begin on a halfword 
boundary. 






OVRD 



when coded as shown* specifies that the expiration date in 
the DSCB should be ignored. 



Example: In the following example* data set A.B.C is deleted 
from two volumes. The expiration date in the identifier 
(format-1) DSCB is ignored. 





SR 




0*0 


X 
X 


SCRATCH 


DELABC 


X 


Check 


Return Codes and 


DELABC 


CAMLST 


SCRATCH*DSA 


DSABC 


DC 




CL44'A.B.C» 


VOLIST 


DC 




H»2* 




DC 




X»30C0200D» 




DC 




CL6'000017» 




DC 




H'O' 




DC 




X'SOCOZOOD" 




DC 




CL6'000018' 




DC 




H'O' 



SET REG TO ZERO 
DELETE DATA SET A.B.C 
FROM TWO VOLUMES, 
IGNORING EXPIRATION 
DATE IN THE DSCB 



DATA SET NAME 
NUMBER OF VOLUMES 
3330 DISK DEVICE CODE 
VOLUME SERIAL NO. 
SCRATCH STATUS CODE 
3330 DISK DEVICE CODE 
VOLUME SERIAL NO. 
SCRATCH STATUS CODE 
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The SCRATCH macro instruction points to the CAMLST macro 
instruction. SCRATCH^ the first operand of CAMLST» specifies 
that a data set be deleted. DSABC* the second operand* 
specifies the virtual storage location of a ^^-byte area into 



^"^ 

\k^ 
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/f^, 
\..^ J^ 












Mhich you have placed the fully qualified name of the data set 
to be deleted. VOLIST» the fourth operand* specifies the 
virtual storage location of the volume list you have built. 
OVRDy the sixth operand* specifies that the expiration date in 
the DSCB of the data set to be deleted be ignored. 

Ulhen you attempt to delete a passMord-protected data set which 
is not also RACF-protected» the operating system issues a 
message (IEC301A) to ask the operator at the console or terminal 
operator of a remote console to enter the password. The data 
set Mill be scratched only if the password supplied is 
associated with a URITE protection mode indicator. The 
protection mode indicator is described under "Chapter 5. 
Password Protecting Your Data Sets" on page 113. 

Control is returned to your program at the next executable 
instruction following the SCRATCH macro instruction. If the 
data set has been successfully deleted* register 15 will contain 
zeros and the scratch status code in the volume list entry for 
each volume will be set to zero. Otherwise* register 15 will 
contain one of the return codes that follow. To determine 
whether the data set has been successfully deleted from each 
volume on which it resides* you must examine the scratch status 
code* the last byte of each entry in the volume list. 

Code Meaning 

4(04) No volumes containing any part of the data set were 
mounted* nor did register contain the address of a 
unit that was available for mounting a volume of the 
data set. The data set may be a VIO data set that was 
not allocated during your job. (This return code is 
accompanied by a scratch status code of 5 in each entry 
of the volume list.) 

8(08) An unusual condition was encountered on one or more 
volumes. 

12(0C) The volume list passed was invalid. The scratch status 
code* the last byte of each volume list entry* will not 
have been modified during scratch processing. 

After the SCRATCH macro instruction is executed* the last byte 
of each 12-byte entry in the volume list indicates the following 
conditions in binary codes? 

Scratch 

Status 

Code Meaning 

All DSCBs for the data set have been deleted from the 
VTOC on the volume pointed to. 

1 The VTOC of this volume does not contain the format-1 
DSCB for the data set to be deleted. 

2 The macro instruction failed when the correct password 
was not supplied in the two attempts allowed* or an 
attempt was made to scratch a VSAM data space or data 
set cataloged in an ICF catalog. 

3 The data set was not deleted from this volume because 
either the OVRD option was not specified or the 
retention cycle has not expired. 

4 A permanent I/O error was encountered* or an invalid 
format-1 DSCB was found when processing this volume* 
or an unexpected error return code was received from 
CVAF. 

5 It could not be verified that this volume was mounted* 
and no device was available on which this volume could 
be mounted. 
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Scratch 

status 

code Meaning 

6 The operator Mas unable to mount this volume. For 
MSS» a volume mount failure occurred. For a 
JESS-managed virtual volume* JES3 Mould not alloM the 
volume to be mounted. 

7 The specified data set could not be scratched because 
it Mas being used. 

8 The DSCB indicates the data set is defined to RACF but 
either the accessor is not authorized to the data set 
or to the volume, or the data set is a VSAM data 
space, or the data set is cataloged in an ICF catalog, 
or the data set is not defined to RACF. 

9 The data set is defined to RACF but its definition 
could not be deleted by RACF. 

RENAMING A DATA SET (RENAME AND CAMLST RENAME): You rename a 
data set that is not cataloged in an ICF or VSAM catalog by 
using the RENAME and CAMLST macro instructions. This causes the 
data set name in all format-1 DSCBs for the data set to be 
replaced by the neM name that you supply. (VIO data sets cannot 
be renamed.) 

If a data set to be renamed is stored on more than one volume, 
either a device must be available on Nhich to mount the volumes, 
or at least one volume must be mounted. In addition, all other 
volumes of the data set must be serially mountable. 

For information on RACF-defined data sets, see Resource Access 
Control Facility (RACF)? General Information Manual . Only an 
accessor Mith alter access authority may rename a RACF-defined 
data set. 

Uhen renaming a data set, you must build a volume list in 
virtual storage. This volume list consists of an entry for each 
volume on Mhich the data set resides. The first two bytes of 
the list indicate the number of entries in the list. Each 
12-byte volume list entry consists of a 4-byte device code, a 
6-byte volume serial number, and a 2-byte rename status code 
Mhich should be initialized to zero. Device codes are presented 
i n Debuggj ng Handbook . Volumes are processed in the order in 
Mhich they appear in the volume list. The first volume on the 
list is processed first. If a volume is not mounted, a message 
is issued to the operator requesting that the volume be mounted. 
(A volume mount message Mill not be issued for an MSS volume; 
hoMever, a status code Mill be returned to your program.) This 
is only done if you indicate the direct access device on Mhich 
unmounted volumes are to be mounted by loading register Mith 
the address of the UCB associated Mith the device to be used. 
(The device must be allocated to your job.) If you do not load 
register Mith a UCB address, its contents must be zero, and at 
least one of the volumes in the volume list must be mounted 
before the RENAME macro instruction is executed. 

If the operator cannot mount a volume in the volume list, a 
reply is i ssued that the request cannot be fulfilled. A status 
code is then set in the last byte of the volume list entry (the 
second byte of the rename status code) for the unavailable 
volume, and the next volume indicated in the volume list is 
processed or requested. 



'\J 
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The format is^ 



r symbol 1 
It stname 



RENAME 
CAMLST 



li stname-addrx 

RENAME 

» dsname-relexp 

> new name-relexp 

»vol list-relexp 






1 i stname-addrx 

points to the parameter list (labeled li stname) set up by 
the CAMLST macro instruction. 

RENAME 

this operand must be coded as shoMn. 

dsname-relexp 

specifies the virtual storage location of a fully qualified 
data set name to be replaced. The area that contains the 
name must be 44 bytes long. The name must be defined by a 
C-type define constant (DC) instruction. 

new name-relexp 

specifies the virtual storage location of a fully qualified 
data set name that is to be used as the neu name. The area 
that contains the name must be 44 bytes long. The name 
must be defined by a C-type Define Constant (DC) 
instruction. 

vol list-relexp 

specifies the virtual storage location of an area that 
contains a volume list. The area must begin on a halfuord 
boundary. 

Example* In the following example^ data set A.B.C is renamed 
D.E.F. The data set resides on tMo volumes. 



SR 
RENAME 



0»0 
DSABC 



SET REG TO ZERO 
CHANGE DATA SET 
NAME A.B.C TO D.E.F 



Check Return Codes and RENAME status Codes 



DSABC 


CAMLST 


RENAME, OLDN 


OLDNAME 


DC 


CL44'A.B.C' 


NEWNAME 


DC 


CL44»D.E.F' 


VOLIST 


DC 


H'Z" 




DC 


X'30C0200D» 




DC 


CL6»000017' 




DC 


H'O* 




DC 


X»30C0200D' 




DC 


CL6'000018» 




DC 


H'O' 



OLD DATA SET NAME 
NEW DATA SET NAME 
TWO VOLUMES 
3330 DISK DEVICE CODE 
VOLUME SERIAL NO. 
RENAME STATUS CODE 
3330 DISK DEVICE CODE 
VOLUME SERIAL NO. 
RENAME STATUS CODE 



The RENAME macro instruction points to the CAMLST macro 
instruction. RENAME, the first operand of CAMLST, specifies 
that a data set be renamed. OLDNAME, the second operand, 
specifies the virtual storage location of a 44-byte area into 
Mhich you have placed the fully qualified name of the data set 
to be renamed. NEWNAME, the third operand, specifies the 
virtual storage location of a 44-byte area into Mhich you have 
placed the neM name of the data set. VOLIST, the fourth 
operand, specifies the virtual storage location of the volume 
list you have built. 
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Control is returned to your program at the next executable 

instruction following the RENAME macro instruction. If the data /t\ 

set has been successfully renamed^ register 15 Mill contain \-^^ 

zeros* and the rename status code in the volume list entry for 

each volume Mill be set to zero. OtherMise> register 15 Mill 

contain one of the return codes beloM. To determine Mhether the 

data set has been successfully renamed on each volume on Mhich 

it resides* you must examine the rename status code* the last 

byte of each entry in the volume list. 

Code Meaning 

4(04) No volumes containing any part of the data set Mere 
mounted* nor did register contain the address of a 
unit that Mas available for mounting a volume of the 
data set to be renamed. The data set may be a VIO data 
set* Mhich can't be renamed. (This return code is 
accompanied by a rename status code of 5 in each entry 
of the volume list.) 

8(08) An unusual condition Mas encountered on one or more 
volumes. 

12(0C) The volume list passed Mas invalid. The rename status 
code* the last byte of each volume list entry* Mill not 
have been modified during rename processing. 

After the RENAME macro instruction is executed* the last byte of 
each 12-byte entry in the volume list indicates one of the 
folloMing conditions in binary code! 

Rename 
status 
Code Meaning 

The format-1 DSCB for the data set has been renamed in /^ ^. 
the VTOC on the volume pointed to. X^V 

1 The VTOC of this volume does not contain the format-1 
DSCB for the data set to be renamed. 

2 The macro instruction failed Mhen the correct passMord 
Mas not supplied in the tMO attempts alloMed* or the 
user tried to rename a VSAM data space or VSAM data 
set cataloged in an ICF catalog. 

3 A data set Mith the neM name already exists on this 
volume. 

4 A permanent I/O error Mas encountered* or an invalid 
format-1 DSCB Mas found Mhen trying to rename the data 
set on this volume* or an unexpected error return code 
Mas received from CVAF. 

5 It could not be verified that the volume Mas mounted* 
and no device Mas available on Mhich the volume could 
be mounted. 

6 The operator Mas unable to mount this volume. For 
MSS* a volume mount failure occurred. For a 
JES3-managed virtual volume* JES3 Mould not alloM the 
volume to be mounted. 

7 The specified data set could not be renamed on this 
volume because it Mas being used. 

8 The data set is defined to RACE but either the 
accessor is not alter authorized to the data set or 
the data set is defined to RACE on multiple volumes. 



Uhen you attempt to rename a passMord-protected data set* the 
operating system issues a message (IEC301A) to ask the operator 
or remote console operator to verify the password. The data set 
Mill be renamed only if the passMord supplied is associated with 



^"^ 
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a URITE protection mode indicator. The protection mode 
indicator is described under "Chapter 5. Password Protecting 
Your Data Sets" on page 111. 



USING VTOC ACCESS MACROS 

VTOC access macros enable you to: 



Determine whether a UCB points to an indexed VTOC (the 
CVAFTST macro) 

Directly access DSCBs and VTOC index records (the CVAFDIR 
macro) 

Read DSCBs in physical-sequential order » beginning with the 
DSCB you specify (the CVAFSEQ macro) 

Read DSCBs in data-set*-nama order using the VTOC index (the 
CVAFSEQ macro) 

Obtain free space information from each of the three index 
maps (the CVAFDSM macro) 

If your program is unauthorized* you must open the VTOC to 
supply a DEB address* created by SAM or EXCP* to the CVAFDIR* 
CVAFDSM* or CVAFSEQ macros; the status of the VTOC Mill then be 
determined by CVAF and indicated in the CVPL by the CVIIVT bit. 

In the sections that follow* VTOC access macros are described in 
general terms. Their syntax is explained in "Appendix A. VTOC 
Access Macros" on page 184. 



#*>^ 



OVERVZEH OF THE CVAFTST MACRO 



The CVAFTST macro determines whether the system supports an 
indexed VTOC* and* if it does* whether the VTOC on the unit 
whose UCB is supplied is indexed or nonindexed. 

You will get a return code of 12 if CVAFTST cannot determine 
whether an indexed or nonindexed VTOC i s on the unit's volume. 
You should not receive a return code of 12 from CVAFTST if you 
have opened a data set (including the VTOC) on the volume. 

You need no authorization to issue the CVAFTST macro. 

The syntax of CVAFTST is explained in "Appendix A. VTOC Access 
Macros" on page 184. Return codes are explained in "Appendix C. 
Return Codes from VTOC Access Macros" on page 221. 



OVERVZEU OF THE CVAFDIR MACRO 



For an indexed or nonindexed VTOC* the CVAFDIR macro may be used 
to: 

• Read or write a DSCB by specifying the name of the data set 
it represents 

• Read or write a DSCB by specifying its address 

In addition* for an indexed VTOC* the macro may be used to: 

• Read or write VTOC index records 

• Read and retain in virtual storage the first high-level 
VIER* and VIERs used during an index search. 

• Read and retain in virtual storage the space map VIRs 

• Free VIRs retained in virtual storage 
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The syntax of CVAFDIR is explained in **Appendix A. VTOC Access 
Macros" on page 184. A description of how to use it is under 
"How to Use the CVAFDIR Macro" on page 59. 

OVERVXEU OF THE CVAFSEQ MACRO 

The CVAFSEQ macro may be used to^ 

• Read an indexed VTOC sequentially* in data-set-name (DSN) 
order 

• Read an indexed VTOC or a nonindexed VTOC in 
physical-sequential order 

A description of how to use it is under "How to Use the CVAFSEQ 
Macro" on page 62. 

The syntax of CVAFSEQ is explained in "Appendix A. VTOC Access 
Macros" on page 184. 

OVERVIEU OF THE CVAFDSN MACRO 

The CVAFDSM macro may be used for an indexed VTOC to: 

• Obtain one or more extents that describe unallocated space 
on the volume 

• Obtain a count of free DSCBs on the VTOC 

• Obtain a count of free VTOC index records in the VTOC index. 

The syntax of CVAFDSM is explained in "Appendix A. VTOC Access 
Macros" on page 184. A description of how to use it is under 
"How to Use the CVAFDSM Macro" on page 63. 



BUFFER LISTS 



A buffer list consists of one or more chained control blocks* 
each with a header and buffer list entries. The header 
indicates whether the buffer list is for DSCBs or VTOC index 
records. The entries point to and describe the buffers. 

Buffer lists can be created in two ways! 

• Directly, when you fill in the arguments and buffer 
addresses of DSCBs or VIRs to be read or written 

• Indirectly, when you code the IXRCDS=KEEP and/or MAPRCDS=YES 
keywords 



o 



J 



//''■> 



\. 



jj 



Buffer List Header 



The header of the buffer list indicates whether the buffer list 
describes buffers for DSCBs or VTOC index records. The DSCB bit 
must be set to one and the VIR bit must be set to zero in order 
for CVAF to process a request to read or write a DSCB. The 
protect key and subpool fields in the buffer list header are 
used by CVAF only if ACCESS=RLSE is coded. 

The buffer list header contains a count of the number of entries 
in the buffer list. 

The forward chain address is used to chain buffer lists 
together, DSCB buffer lists must not be chained to VIR buffer 
lists and VIR buffer lists must not be chained to DSCB buffer 
lists. 

The format of the buffer list header is shown in Figure 17 on 
page 57. 
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Name 


Offset 


Bytes 


Description 


BFLHDR 


0(00) 


8 


Buffer list header 


BFLHNOE 


0(00) 


1 


Number of entries 


BFLHFL 


1(01) 


1 


Flag byte and key 


BFLHKEY 




xxxx .... 


Protect key of buffer 
list and buffers 


BFLHVIR 




1... 


Buffer list entries 
describe VIRs 


BFLHDSCB 




.,,. .1.. 


Buffer list entries 
describe DSCBs 


BFLHRSV6 




X. 


Reserved 


BFLHRSV7 




X 


Reserved 


BFLHRSV 


2(02) 


1 


Reserved 


BFLHSP 


3(03) 


1 


Identifies the sub- 
pool of buffer list 
and buffers 


BFLHFCHN 


<i(04) 


4 


Forward chain address 
of next buffer list 


Figure 17. 


Format of 


a Buffer List 


Header 



Buffer List Entry 



^**v 



A buffer list contains one or more entries. Each entry provides 
the buffer address* the length of the DSCB or VIR, the argument* 
and an indication whether the argument is an RBA» a TTR» or a 
CCHHR. 

The fields and bit uses are listed below. 

For a VIR buffer » the TTR and CCHHR bits must be and the 
RBA bit must be 1. 

For a DSCB buffer » the RBA bit must be 0» and only one of 
the TTR or CCHHR bits may be set to 1. 

The BFLEAUPD bit i s an output indicator from CVAF that the 
BFLEARG field of a VIR buffer list was updated. 

The BFLEMOD bit indicates that a VIR buffer was modified and 
must be written; if no BFLEMOD bits are on in any of the 
entries for a CVAFDIR ACCESS=WRITE, all buffers are written. 

The BFLESKIP bit is used to cause an entry to be ignored. 

The BFLEIOER bit i s an output indicator from CVAF to 
indicate an I/O error occurred during reading or writing of 
the DSCB or VIR. 

The BFLELTH field is the length of the buffer; for a DSCB 
buffer, the length must be 96 or 140; for a VIR buffer » the 
length must be the length of the buffer divided by 256. 

The BFLEARG field is the argument of the DSCB or VIR; the 
three possible formats of the 5-byte field are? 

CCHHR=5 byte CCHHR 

TTR=0TTR0 

- RBA=One byte of followed by a 4-byte RBA 

The format of the buffer list entry is shown in Figure 18 on 
page 58. 
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Name 


Offset 


Bytes 


Description 


BFLE 


0(00) 


12 


Buffer list entry 


BFLEFL 


0(00) 


1 


Flag byte 


BFLERBA 




1 


Argument is RBA 


BFLECHR 




.1 


Argument i s CCHHR 


BFLETTR 




..1 


Argument i s TTR 


BFLEAUPD 




•«*X ««•« 


CVAF updated argument 
field 


BFLEMOD 




1... 


Data in buffer has 
been modified 


BFLESKIP 




1., 


Skip this entry 


BFLEIOER 




1. 


I/O error 


BFLERSV7 




X 


Reserved 


BFLERSV 


1(01) 


1 


Reserved 


BFLELTH 


2(02) 


1 


Length of VIR buffer 
divided by 256 or 
length of DSCB buffer 


BFLEARG 


3(03) 


5 


Argument of VIR 
or DSCB 


BFLEATTR 


4(04) 


3 


TTR of DSCB 


BFLEARBA 


4(04) 


4 


RBA of VIR 


BFLEBUF 


8(08) 


4 


Buffer address 


Figure 18. 


Format of 


a Buffer List 


Entry 



THE CVAF PARAHETER LIST (CVPL) 



A CVPL is generated by using the CVAFDIR, CVAFDSM, or CVAFSEQ 
macro with MF=L or MF=I specified or with MF not specified (MF=I 
i s the default) . 

The CVPL passes information to CVAF. CVAF» in turnt returns 
information in the CVPL. The CVIIVT bit indicates whether an 
indexed or nonindexed VTOC is being accessed. The CVSTAT field 
contains feedback when an error occurs. The address of the map 
records buffer list is returned in the CVMRCDS field. The 
address of the VIER buffer list is returned in the CVIRCDS 
field. The CVAF I/O area address is returned in the CVIOAR 
field. 

The CVPL generated by the MF=L or MF=I form of the CVAFDIR, 
CVAFDSM, or CVAFSEQ macro may be used (through the MF=E keyword) 
to execute a different macro from the one that generated the 
CVPL. 

The format of the CVPL is shown in Figure 19 on page 59. 






IDENTIFYING THE VTOC 



The VTOC must be identified to CVAF by supplying either the 
address of a UCB (with the UCB keyword) or the address of a DEB 
opened to the VTOC (with the DEB keyword). 



An unauthorized caller must supply the address of a SAM o 
DEB open to the VTOC. The DEB can be obtained by opening 
using the RDJFCB and OPEN TYPE=J macros. The DCBs DDNAME 
that of a DD statement allocated to the unit whose VTOC i 
accessed. After issuing the RDJFCB macro, the JFCBDSNM f 
overlaid with the data set name of the format-4 DSCB: ^^X 
The DCB is opened for INPUT using OPEN TYPE=J. The DEB a 
is in DCB field, DCBDEBA. The OPEN macro is described un 
"OPEN — Initialize Data Control Block for Processing the J 
page 147 and the RDJFCB macro is described under "RDJFCB— 
Job File Control Block" on page 148. 



r EXCP 
a DCB 
i s 

s to be 

ield is 

•04'. 

ddress 

der 

FCB" on 

—Read a 
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Name 



Offset 



Bytes 



Description 



CVPL 








CVLBL 


00(00) 


4 


EBCDIC "CVPL" 


CVLTH 


0<»(0^) 


2 


Length of parameter list 


CVFCTN 


06(06) 


1 


Function Byte 


CVDIRD 






X»01'-CVAFDIR ACCESS=READ 


CVDIWR 






X»02'-CVAFDIR ACCESS=WRITE 


CVDIRLS 






X'03'-CVAFDIR ACCESS=RLSE 


CVSEQGT 






X'04»-CVAFSEQ ACCESS=GT 


CVSEQGTE 






X'05»-CVAFDIR ACCESS=GTEQ 


CVDMMAP 






X»OA»-CVAFDSM ACCESS=MAPDATA 


CVSTAT 


07(07) 


1 


Status Information 


CVFLl 


08(08) 


1 


First Flag Byte 


CVIIVT 




1.,. , 


Indexed VTOC Accessed 


CVIIOAR 




,1.. , 


IOAREA=KEEP 


CV1P6M 




..1. , 


BRANCH=(YES,PGM) 


eVlMRCDS 




..,1 , 


MAPRCDS=YES 


CVIIRCDS 




1 


L.., IRCDS=KEEP 


CVIMAPIX 




• • • • « 


1.. MAP=INDEX 


CVIMAPVT 




• • • • « 


.1. MAP=VTOC 


CVIMAPVL 




• • • • « 


..1 MAP-VOLUME 


CVFL2 


09(09) 


1 


Second Flag Byte 


CV2HIVIE 




1... . 


HIVIER=YES 


CV2VRF 




.1.. , 


... VRF Information Exists 


CV2CNT 




..1. . 


COUNT=YES 


CV2RCVR 




...1 . 


RECOVER=YES 


CV2SRCH 




] 


SEARCH=YES 


CV2DSNLY 




« * • • « 


1.. DSNONLY=YES 


CV2VER 




• • • • « 


.1. VERIFY=YES 


CV2RSV7 




• • • • • 


..X Reserved 


CVRSVB 


lO(OA) 


2 


Reserved 


CVUCB 


12(0C) 


4 


UCB address 


CVDSN 


16(10) 


4 


Data set name address 


CVBUFL 


20(14) 


4 


Buffer list address 


CVIRCDS 


24(18) 


4 


Index VIRs buffer list 
address 


CVMRCDS 


28(1C) 


4 


Map VIRs buffer list 
address 


CVIOAR 


32(20) 


4 


I/O area address 


CVDEB 


36(24) 


4 


DEB address 


CVARG 


40(28) 


4 


Argument address 


CVSPACE 


44(2C) 


4 


SPACE parameter list 
address 


CVEXTS 


48(30) 


4 


Extent table address 


CVBUFL2 


52(34) 


4 


New VRF VIXM buffer list 
address 


CVVRFDA 


56(38) 


4 


VRF data address 


CVCTAR 


60(3C) 


4 


Count area address 


Figure 19, 


Format of 


the CV/ 


IF Parameter List 



If a CVAF macro call has specified IOAREA=KEEP, then a 
subsequent CVAF call using a different CVPL may omit the UCB and 
DEB keywords* and supply the lOAREA address from the other CVPL. 
You can use the 10 AREA keyword to do this. 

The above does not apply to the CVAFTST macro. Only a UCB may 
be supplied to identify the VTOC» and no authorization is 
required. 



HOU TO USE THE CVAFDIR MACRO 



CVAFDIR may be used to read or write a DSCB. For indexed VTOCs> 
CVAFDIR may be used to read or write VTOC index records. 
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After a CVAFDIR call, the CVAF parameter list bit, CVIIVT, may 
be tested to determine if the VTOC is indexed or nonindexed. 

Specifying a Data Set Name to Read or Urite a DSCB 

To read or Mrite a DSCB by specifying only a data set name, 
ACCESS=READ or ACCESS=WRITE must be coded. 

The address of the data set name is supplied in the DSN keyword; 
the buffer list address is supplied in the BUFLIST keyMord. 

The buffer list must have at least one buffer list entry with 
the skip bit off and a pointer to a 96- or 140-byte buffer. 
Buffer lists may be chained together, but only the first 
eligible entry Mill be used. 

For an indexed VTOC, the index will be searched for the data set 

name and, if it is found, the DSCB argument obtained will be put 

in the buffer list entry and used to read or write the DSCB. If 

the data set name is not found in the index, a key search of the 
VTOC will be performed. 

For a nonindexed VTOC, a channel program will be used to do a 
key search of the VTOC to locate the data set name and read or 
write the DSCBs. If the data set name is found, the DSCB 
argument will be put in the buffer list entry. 

The DSCB argument returned in the buffer list entry will be in 
the format determined by the buffer list entry bits BFLECHR or 
BFLETTR. 

If the data set name is not found in the VTOC, register 15 will 
contain a return code of 4 and CVSTAT will contain an error code 
of 1. 

Specifying the DSCB Location O" 

To read or write a DSCB by specifying the DSCB*s location, 
either ACCESS=READ or ACCESS=WRITE must be coded. The DSN 
keyword must be supplied but will not be used for a 140-byte 
DSCB. A buffer list address must be supplied in the BUFLIST 
keyword. The buffer list must have at least one buffer list 
entry with the skip bit off and pointing to a 96- or 140-byte 
buffer. Buffer lists may be chained together, but only the 
first eligible entry will be used. This procedure is the same 
for both indexed and nonindexed VTOCs. 

If the buffer is for a 96-byte read or write, a channel program 
will be used to verify that the key in the DSCB is the same as 
the ^4-byte dato set name provided before reading or writing the 
DSCB. If the buffer is for a 140-byte read or write, a channel 
program will be used to read or write the DSCB at the location 
provided in the buffer list entry. The data set name will not 
be used, and the DSCB key will not be read. 

If VERIFY=YES is coded and the write is for a 140-byte DSCB, the 
channel program used for the write will verify that the DSCB is 
a format-O DSCB prior to the write. 

Reading or Uriting VTOC index Records 

VIRs may be read or written explicitly using the BUFLIST keyword 
or may be read implicitly using the IXRCDS and MAPRCDS keywords. 
A buffer list address may be supplied in the BUFLIST keyword to 
read or write one or more VIRs. The buffer list header must 
have the VIR bit set to one and the DSCB bit set to zero. Each 
entry in the buffer list (and subsequent buffer lists if more 
than one is chained) is inspected. If the skip bit is set to 
zero, the RBA bit is set to one (and the CCHHR and TTR bits are 
set to zero), and the buffer address is nonzero, the entry will 
be processed. The RBA in the argument field of the buffer list 
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o 



entry is used to read or Mrite a VIR using the buffer address. 
Read and Mrite requests Mill be in the order of entries in the 
buffer list(s). 

For a Mrite request » the modification bit in the buffer list 
entries is inspected. If the bit is not set in any entry^ all 
are Mritten. The modification bit is set to zero for entries 
Mhose VIR is Mritten. 

Map records and the first high-level VTOC index entry record may 
be read by supplying the keywords MAPRCDS=YES and/or 
IXRCDS=KEEP» and not supplying an address in the CVAF parameter 
list CVMRCDS/CVIRCDS fields. 



Reading flap Records and VIERS 



o 



To read and retain in virtual storage the VTOC index map records 
and first high-level VIER, either ACCESS=READ or ACCESS=WRITE 
must be coded. Neither the DSN field nor the BUFLIST field is 
requi red. 

MAPRCDS=YES must be coded to read and retain map records. The 
CVAF parameter list field CVMRCDS must be zero. CVAF Mill 
obtain a buffer list Mith the number of entries and buffers 
required to read all the map VIRs. The buffer list address Mill 
be put in the CVMRCDS field by CVAF. 

IXRCDS=KEEP is coded in order to read and retain the first 
high-level VIER and (if an index search is required) all VIERs 
read. If the CVAF parameter list field CVIRCDS is zero, CVAF 
Mill obtain a buffer list Mith entries and buffers and read the 
first high-level VIER. The number of entries and number of 
buffers are determined by CVAF. If CVIRCDS is not zero» only 
VIERs required for an index search Mill be read. 

The integrity of the maps and VIER read can only be ensured if 
you are enqueued on the VTOC and, in the case of shared DASD, 
reserved to the unit. 

Map and VIER buffers obtained by CVAF, and retained, must be 
released by a subsequent CVAF call. 



Releasing Buffers and Buffer Lists Obtained by CVAF 



There are three Mays to release buffers and buffer lists 
obtained by CVAF. 

• Code MAPRCDS=NO or MAPRCDS=(NO,addr) for any specification 
of ACCESS, to free the MAP records buffer list. 

• Code IXRCDS=NOKEEP or IXRCDS=(NOKEEP,addr) for any 
specification of ACCESS, to free the index records buffer 
list. 

• Code ACCESS=RLSE and supply a buffer list address through 
the BUFLIST keyMord for a subsequent CVAF call. 

CVAF Mill free all eligible buffers, and buffer lists if they 
become empty. Eligible buffers are those pointed to by buffer 
list entries Mith the skip bit off. A buffer list Mill be freed 
if no buffer list entry has the skip bit on. If buffer lists 
are chained together, all buffer lists Mill be checked and freed 
if appropriate. 

You must ensure that you do not request CVAF to release the same 
buffer list tMice by supplying its address in more than one 
place. 



%J 
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HOU TO USE THE CVAFSEQ MACRO 

Each CVAF call will return one of the folloMing: 

• One format-1 or format-^ DSCB in indexed (data-set-name) 
order 

• One or more DSCBs in physical-sequential order (but only one 
DSCB can be requested by an unauthorized caller) 

• The next data set name in the index 

The DSCBs are read into buffers supplied through the BUFLIST 
keyword. 

The argument of each DSCB read is also supplied in the buffer 
list. DSCBs of 96 bytes must be requested in the buffer list 
for indexed access; 140 bytes is required for 
physical-sequential access. 

If indexed order is chosen» the VTOC, index is used to return 
each format-1 or format-4 DSCB whose name is in the index. An 
option (DSNONLY=YFS) allows only the data set names in the VTOC 
indexy and not the DSCBs^ to be obtained. In this case* the 
CCHHR of the DSCB is returned in the argument area supplied 
through the ARG keyword. The DSN area supplied is updated at 
each CVAFSEQ call to contain the data set name of each DSCB 
read. 

Initiating Indexed Access (DSN Order) 

To initiate indexed access (DSN order)* either supply in the 
area coded through the DSN keyword 44 bytes of binary zeros (to 
indicate the first data set name in the index) or supply the 
data set name you wish to serve as the starting place for the 
index search. 

The name returned in the DSN area will be the one equal to or 
greater than the DSN supplied* depending on the specification of 
the ACCESS keyword. The DSN field is updated by CVAF. 

The ACCESS keyword determines whether the search is for a DSN 
greater than or equal to that supplied. 

If DSNONLY=NO is coded* the DSCB and argument are returned to 
you using the buffer list provided through the BUFLIST keyword. 
The first entry in the buffer list with a skip bit of zero and a 
nonzero buffer address is used. The argument value is supplied 
if either the TTR or CCHHR bit is set in the buffer list entry. 
The default is CCHHR. The DSCB size in the buffer list entry 
must be 96 bytes for indexed access. 

If DSNONLY=YES is coded, the CCHHR argument is supplied in the 
ARG area. 

Note that the data set name of the format-4 DSCB is in the index 
and that its name (44 bytes of X*04'') may be returned to you. 
The format-4 DSCB's name is likely to be the first data set name 
in the VTOC index. 






Initiating Physical-Sequential Access 



To initiate physical-sequential access* the DSN keyword must be 
omitted or DSN=0 must be coded. The argument field in the first 
buffer list entry must be initialized to zero or to the argument 
of the DSCB to begin the read. If the argument is zero* the 
argument used will be the start of the VTOC. 

The DSCB size must be set to 140 in buffer list entries. 
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The specification of ACCESS Mill determine uihether the DSCB 
Mhose argument is supplied or the DSCB folloMing it is to be 
read. 

For example* to read the first DSCB (the format-4 DSCB) in the 
VTOC, the BFLEARG in the first buffer list entry may be set to 
zero, and ACCESS=GTEQ coded in the CVAFSEQ macro. If ACCESS=GT 
is subsequently coded, the second DSCB (the first format-5 DSCB) 
is read. 

If you are authorized, as many DSCBs as there are entries in the 
buffer list Mill be read Mith a single CVAF call. Only one DSCB 
Mill be read if you aren't authorized. 

Only one buffer list is used; a second buffer list chained to 
the first Mill not be inspected. All entries in the buffer list 
Mill be used for authorized callers. The skip bit Mill not be 
inspected. Each entry must have a buffer address, the length 
field set to 140, and the TTR or CCHHR bit set (if neither bit 
is set, the CCHHR bit Mill be set on). Only the first entry 
Mill be used for unauthorized callers. The argument field of 
each buffer list entry Mill be updated by CVAF Mith the argument 
of the DSCB. The argument value is returned in either TTR or 
CCHHR format, depending on Mhether the TTR or CCHHR bit is set 
in the buffer list entry. The default is CCHHR. 

Only the argument in the first entry is used to begin the 
search. Arguments in subsequent entries are not inspected. If a 
nonzero argument value is supplied in the first entry, there 
must be a DSCB Mith that argument. 

End-of-data is indicated Mith a return code of 4 in register 15 
and CVSTAT set to X'20'. Each buffer list entry folloMing the 
last DSCB read has its argument field set to zero (this may be 
the first entry if no DSCBs are read). 

Note that all DSCBs, including format-0 DSCBs, are read. You 
cannot be certain that you have read all format-1 through -6 
DSCBs until the entire VTOC has been read. For a nonindexed 
VTOC, the CCHHR of the last format-1 DSCB is contained in the 
format-4 DSCB field DS4HPCHR; format-2 through -6 DSCBs may 
reside beyond that location. For an indexed VTOC, the VMDS 
contains information about Mhi ch DSCBs are format-0 DSCBs. 



HON TO USE THE CVAFDSN MACRO 



ACCESS=MAPDATA is used to obtain information contained in the 
space maps. 

To count the number of unallocated VIRs in the VTOC index space 
map (VIXM), COUNT=YES and MAP=INDEX are coded. The number of 
unallocated VIRs is returned in the 4-byte area supplied through 
the CTAREA keyMord. 

To count the number of format-0 DSCBs, COUNT=YES and MAP=VTOC 

are coded. The number of format-0 DSCBs in the VTOC map of 

DSCBs VMDS is returned in the 4-byte area supplied through the 
CTAREA keyNord. 

To obtain one or more free space extents from the VTOC pack 
space map (VPSM), COUNT=NO and MAP=VOLUME are coded. The 
extents are returned in the area supplied through the EXTENTS 
keyMord. Each extent is returned in a 5-byte XXYYZ format, the 
same as for a format-5 DSCB extent, Mhere XX is the relative 
track address (RTA) of the first track of the extent, YY is the 
number of Mhole cylinders in the extent, and Z is the number of 
additional tracks in the extent. The RTA supplied to CVAF in 
the first (or only) extent Mill serve as a starting place for 
the VPSM search; the extent returned Mill be the next free 
extent Mith a higher starting RTA than the one supplied. 
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If all the unallocated extents in the VPSM are supplied before 
filling in all the extents supplied^ the remaining extents are 
set to zero. Register 15 is set to ^ on return* with the CVSTAT 
field in the CVPL set to X'20' to indicate the end of data. 



J 



VTOC SERZALXZATZON 



REGZSTER USAGE 



It is your responsibility to serialize access to the VTOC and 
the VTOC index when you use VTOC access macros. The ENQ or 
RESERVE macro instruction with the SYSTEMS parameter is used for 
this serialization. The qname (major name) is SYSVTOC; the 
rname (minor name) is the 6-byte volume serial number of the 
volume. Only authorized programs may ENQ RESERVE using the 
SYSVTOC qname. 

The SYSVTOC qname does not serialize access to the format-1 DSCB 
for a data set. You must allocate the data set with disposition 
OLD, MOD, or NEW (not SHR). This causes the proper ENQ, which 
ensures no other job will update that data set's format-1 DSCB. 

Updates to the VTOC index performed without proper serialization 
will compromise the integrity of the VTOC or VTOC index. 



Register 1 is used to contain the address of the CVAF parameter 
list (CVPL). Register 15 is used to contain the return code when 
processing has completed for a function. 



VTOC ERROR DZA6N0SZS AND RECOVERY 

ACTZONS TAKEN UHEN AN ERROR OCCURS 

These actions are taken if an error occurs^ 



If an index structure error is detected, DADSM or CVAF will 
cause the VTOC index to be disabled. The indexed VTOC bit 
will be zeroed in the format-4 DSCB. A software error 
record will be written to SYSl.LOGREC. A system dump is 
taken. The VTOC will be converted to a nonindexed format at 
the next DADSM allocate or extend call. 

If a program check, machine check, or other error occurs 
while using a VTOC access macro, a SYSl.LOGREC message is 
written and a system dump is taken. 

An error code is put in the CVSTAT field of the CVPL. The 
values and explanations of these error codes are listed in 
""Appendix D. VTOC Error Message and Associated Codes" on 
page 223. 






RECOVERZNG FROM SYSTEM OR USER ERRORS 



Neither the VTOC nor the VTOC index need be recovered from a 
user error caused by an unauthorized user, since an unauthorized 
user cannot modify a VTOC. 

A system error will affect a VTOC and VTOC index, probably by 
interrupting DADSM while it is updating, thus leaving the VTOC 
and/or the VTOC index in a partially updated state. Both the 
VTOC and the VTOC index are designed to cause DADSM to recover 
from such an interruption. 

For a nonindexed VTOC (or a VTOC with an index that has been 

disabled), a subsequent call to DADSM ALLOCATE or EXTEND will 

cause VTOC convert routines to reestablish the free space 
(format-5 DSCBs). 



a 
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CTF TRACE 



For an indexed VTOC» a subsequent call to any DADSM function 
Mill cause the recovery of the previous interrupt (either by 
backing out or completing the interrupted function). 



A trace facility exists to trace all CVAF calls for VTOC index 
output I/0» all VTOC output I/0» and all VTOC index and space 
map modifications. See Common VTOC Access Facility Diagnosis 
Reference for information on this facility. 



LISTING A VTOC AND VTOC INDEX 



A VTOC and VTOC index can be listed using the lEHLIST utility 
program. Dump» formatted^ or abridged listings can be obtained 
by using the LISTVTOC command of lEHLIST. 
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CHAPTER 3. EXECUTING YOUR OWN CHANNEL PROGRAMS (EXCP) 



The execute-channel-program (EXCP) macro instruction provides 
you Mith complete control of the device characteristics and the 
organizing of data. This chapter contains a general description 
of the function and application of the EXCP macro instruction^ 
accompanied by descriptions of specific control blocks and macro 
instructions used uiith EXCP. Factors that affect the operation 
of EXCP» such as device variations and program modification* am 
also discussed. 

Before reading this chapter* you should be familiar Mith system 
functions and with the structure of control blocks* as well as 
with the operational characteristics of the I/O devices required 
by your channel programs. Operational characteristics of 
specific I/O devices are contained in IBM publications for each 
dev ice. 

You also need to understand the information in these 
publi cations* 

• Data Management Services contains the standard procedures 
for I/O processing under the operating system. 

• QS/VS--DOS/VSE--VM/370 Assembler Language contains the 
information necessary to code programs in the assembler 
language. 

• Data Management Macro Instructions describes the system 
macro instructions that can be used in programs coded in the 
assembler language. 

• Debugging Handbook * Volumes 2 and 3, contains format and ( .) 
field descriptions of the system control blocks referred to ''K.^ 
in this chapter. 

The execute-channel-program (EXCP) macro instruction causes a 
supervisor-call interruption to pass control to the EXCP 
processor. (I/O process is the name we will use for the EXCP 
processor and the I/O supervisor. For our purposes* it's 
unnecessary to understand how input/output processing is divided 
between the two.) EXCP also provides the I/O supervisor with 
control information regarding a channel program to be executed. 
Ulhen an IBM access method is being used* an access method 
routine is responsible for issuing EXCP. If you are not using 
an IBM access method* you must issue EXCP in your program. (The 
EXCP macro instruction cannot be used to process SYSIN or SYSOUT 
data sets.) 

You issue EXCP primarily for I/O programming situations to which 
the standard access methods do not apply. If you are writing 
your own access method* you must include EXCP for I/O 
operations. EXCP must be used for processing nonstandard 
labels* including reading and writing labels and positioning 
magnetic tape volumes. 

To issue EXCP* you must provide a channel program (a list of 
channel command words) and several control blocks in your 
program area. The I/O process then schedules I/O requests for 
the device you have specified* executes the specified I/O 
commands* handles I/O interruptions* directs error recovery 
procedures* and posts the results of the I/O requests. 
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EXECUTING CHANNEL PROGRAMS IN SYSTEM AND PROBLEM PROGRAMS 



SYSTEM USE OF EXCP 



o 



#1 

^1 J 



This section briefly explains the procedures performed by the 
system and the programmer Mhen EXCP is issued by the routines of 
IBM access methods. The additional procedures that you must 
perform Mhen issuing EXCP yourself are then described by direct 
compari son. 



Mhen using an IBM access method to perform I/O operations^ the 
programmer is relieved of coding channel programs and 
constructing the control blocks necessary for the execution of 
channel programs. To permit I/O operations to be handled by an 
access method* the programmer need only issue the folloNing 
macro instructions: 

• A DCB macro instruction* which produces a data control block 
(DCB) for the data set to be retrieved or stored 

• An OPEN macro instruction that initializes the data control 
block and produces a data extent block (DEB) for the data 
set 

• A macro instruction (for example* GET or URITE) that 
requests I/O operations 

Access method routines Mill then: 

1. Create a channel program that contains channel commands for 
the I/O operations on the appropriate device 

2. Construct an input/output block (lOB) that contains 
information about the channel program 

3. Construct an event control block (ECB) that is later posted 
Mith a completion code each time the channel program 
terminates 

4. Issue an EXCP macro instruction to pass the address of the 
lOB to the routines that initiate and supervise the I/O 
operati ons 

The I/O process consists of: 

5. Constructing a request queue element (RQE) for scheduling 
the request 

6. If the requestor is in a V=V address space* fixing the 
buffers so that they cannot be paged out and translating the 
requestor's virtual channel program into a real channel 
program 

7. Issuing a start I/O (SIO) instruction to cause the channel 
to execute the real channel program 

8. Processing I/O interruptions and scheduling error recovery 
procedures Mhen necessary 

9. Posting a completion code in the event control block after 
the channel program has been executed 

Note: If the requestor is an authorized program in a V=R 
address space* a real channel program is provided* so item 6 is 
not performed. 

The programmer is not concerned Mith these procedures and does 
not knoM the status of I/O operations until they are completed. 
Device-dependent operations are limited to those provided by the 
macro instructions of the particular access method selected. 
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USE OF EXCP IN PROBLEM PROGRAMS 



To issue the EXCP macro instruction directly* you must folloM 
the procedures that the access methods Mould perform* as 
summarized in items 1 through 4 of the preceding discussion. 
You must* in addition to constructing and opening the data 
control block Mith the DCB and OPEN macro instructions* 
construct a channel program* an input/output block* and an event 
control block before you can issue EXCP. The I/O process 
generally handles items 5 through 9. 

After issuing EXCP* you should issue a UAIT macro instruction* 
specifying the address of the event control block* to determine 
ixihether the channel program has terminated. If volume switching 
is necessary* you must issue an EOV macro instruction. Uhen all 
processing of the data set has been completed* you must issue a 
CLOSE macro instruction to restore the data control block. 



EXCP OPERATIONS IN A V=R ADDRESS SPACE 



Usei — constructed channel programs for I/O operations of an 
authorized program in a V=R address space are not translated. 
Because the address space is V=R* any CCUs created by the user 
have correct real data addresses. (Translation Mould only 
re-create the user's channel program* so the CCUIs &rG used 
directly.) 

Modification of an active channel program by data read in or by 
processor instructions is legitimate in a V=R address space* but 
not in a V=V address space. 



EXCP REQUIREMENTS 



This section describes the channel program that you must provide 
in order to issue EXCP. The control blocks that you must either 
construct directly* or cause to be constructed by use of macro 
instructions* aret also described. 



CHANNEL PROGRAM 




Channel command Mord operation codes used Mith specific I/O 
devices can be found in IBM publications for those devices. All 
channel command Mord operation codes described in these 
publications can be used. In addition* both data chaining and 
command chaining may be used. 

To specify either data chaining or command chaining* you must 
set appropriate bits in the channel command Mord* and indicate 
the type of chaining in the input/output block. Both data and 
command chaining should not be specified in the same channel 
command Mord* if they are, data chaining takes precedence. 

EXCP does not support channel programs that modify themselves* 
regardless of the method of modification: data chaining* command 
chaining* or a program to do the modification. The intended 
modification in virtual storage has no effect on the running 
real-channel program (see "Modification of a Channel Program 
during Execution** on page 71). 



\J 
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CONTROL BLOCKS 



o 



Uhen using EXCP» you must be familiar Mith the function and 
structure of the lOB, the ECB, the DCB, the DEB, and the IDAW. 
lOB and ECB fields are illustrated under "Control Block Fields" 
on page 95. DCB fields are illustrated under "Macro 
Specifications for Use with EXCP" on page 80. The handling of 
IDAUs is described under "SIO Appendage" on page 100. Brief 
descriptions of these control blocks folloM. 



Input/Output Block (lOB) 



The input/output block is used for communication between the 
problem program and the system. It provides the addresses of 
other control blocks, and maintains information about the 
channel program, such as the type of chaining and the progress 
of I/O operations. You must define the input/output block and 
specify its address as the only parameter of the EXCP macro 
instruction. 



Event Control Block (ECB) 



The event control block provides you with a completion code that 
describes whether the channel program was completed with or 
without error. A UAIT macro instruction, which can be used to 
synchronize I/O operations with the problem program, must 
identify the event control block. You must define the event 
control block and specify its address in the input/output block. 



Data Control Block (DCB) 



^Il, | .-jX 



The data control block provides the system with information 
about the characteristics and processing requirements of a data 
set to be read or written by the channel program. A data 
control block must be produced by a DCB macro instruction that 
includes parameters for EXCP. If appendages are not being used, 
a short DCB is constructed. Such a DCB does not support reduced 
error recovery. You specify the address of the data control 
block in the input/output block. 



Data Extent Block (DEB) 



The data extent block contains one or more extent entries for 
the associated data set, as well as other control information. 
An extent defines all or part of the physical boundaries on an 
I/O device occupied by, or reserved for, a particular data set. 
Each extent entry contains the address of a unit control block 
(UCB), which provides information about the type and location of 
an I/O device. More than one extent entry can contain the same 
UCB address. For all I/O devices supported by the operating 
system, the data extent block is produced during execution of 
the OPEN macro instruction for the data control block. The 
system places the address of the data extent block into the data 
control block. 



CHANNEL PROGRAM EXECUTION 



This section explains how the system uses your channel program 
and control blocks after you issue EXCP. 



INITIATION OF THE CHANNEL PROGRAM 



By issuing EXCP, you request the execution of the channel 
program specified in the input/output block. The I/O process 
validates the request by checking certain fields of the control 
blocks associated with this request. If the I/O process detects 
invalid information in a control block, it initiates abnormal 
termination procedures. 
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The EXCP processor gets: 

• The address of the data control block from the input/output 
block 

• The address of the data extent block from the data control 
block 

• The address of the unit control block from the data extent 
block 

It places the IOB» TCB» DEB» and UCB addresses and other 
information about the channel program into an area called a 
request queue element (RQE). (Unless you are providing 
appendage routines (described under '^Appendages'* on page 72) you 
should not be concerned Mith the contents of RQEs.) 

If you have provided a start I/O (SIO) appendage^ the EXCP 
processor noM passes control to it. The return address from the 
SIO appendage determines whether the EXCP processor must! 

• Execute the I/O operation normally* or 

• Skip the I/O operation. 

For a description of the SIO appendage and its linkage to the 
EXCP processor » see ''Appendages" on page 72. 

If you are issuing EXCP from a V=V address space* the channel 
program you construct contains virtual addresses. Because 
channel subsystems cannot use virtual addresses* the EXCP 
processor must* 

• Translate your virtual channel program into one that uses 
only real addresses. 

• Fix in real storage the pages used as I/O areas for the data (7 ^i 
transfer operations specified in your channel program. '\^ 

The EXCP processor builds the translated (real) channel program 
in a portion of real storage. 

For direct access devices* specify the seek address in the 
input/output block. The I/O supervisor constructs a command 
chain to issue the seek* set file mask specified in the data 
extent block* and pass control to your real channel program. 

If your channel program begins Mith a locate-record command* the 
I/O process builds a def ine-extent command and passes control to 
your real channel program. (You cannot i ssue the initial seek* 
set file mask* or define extent. The file mask is set to 
prohibit seek-cylinder commands* or* if space is allocated by 
tracks* seek-head commands. If the data set is open, for INPUT* 
Mrite commands are also prohibited.) 

For a magnetic tape device* the I/O supervisor constructs a 
command chain to set the mode specified in the data extent block 
and passes control to your real channel program. (You cannot 
set the mode yourself.) 

If the I/O device is other than a direct access device or a 
magnetic tape device* the I/O supervisor then places the address 
of the starting CCU of the channel program into the channel 
address Mord (CAM) and issues a start I/O (SIO) instruction. 
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NODZFICATXON OF A CHANNEL PROGRAN DURING EXlOuTIuN 






Any problem program that modifies an active channel program with 
CPU instructions or Mith data read in by an I/O operation must 
be run in a V=R address space. It cannot run in a V=V address 
space because of the channel program translation performed by 
the I/O supervisor. (In a V=V address spacer an attempt to 
modify an active channel program affects only the virtual image 
of the channel program* not the real channel program being 
executed by the channel subsystem.) 

A program of this type can be changed to run in a V=V address 
space by issuing another EXCP macro for the modified portion of 
the channel program. 



COHPLETION OF EXECUTION 






The system considers the channel program completed uihen it 
receives an indication of a channel-end condition in the channel 
status Mord. Unless a channel-end or abnormal-end appendage 
directs otherMise* the request queue element for the channel 
program is made available* and a completion code is placed into 
the event control block. The completion code indicates whether 
errors are associated Mith channel end. If device end occurs 
simultaneously Mith channel end* errors associated Mith device 
end (that is* unit exception or unit check) are also accounted 
for. 

If device end occurs after channel end* and an error is 
associated Mith device end* the completion code in the event 
control block does not indicate the error. HoMever* the status 
of the unit and channel is saved by the I/O supervisor for the 
device* and the UCB is marked as intercepted. The input/output 
block for the next request directed to the I/O device is also 
marked as intercepted. The error is assumed to be permanent* 
and the completion code in the event control block for the 
intercepted request indicates interception. The DCBIFL6S field 
of the data control block is also flagged to indicate a 
permanent error. Note that if a Mri te-tape-mark or 
erase-long-gap CCU is the last or only CCU in your channel 
program* the I/O process Mill not attempt recovery procedures 
for device end errors. In these circumstances* command chaining 
a NOP CCW to your Mri te-tape-mark or erase-long-gap CCW ensures 
initiation of device-end error recovery procedures. 

To be prepared for device-end errors* you should be familiar 
Mith device characteristics that can cause such errors. After 
one of your channel programs has terminated* you should not 
release buffer space until you have determined that your next 
request for the device has not been intercepted. You may 
reissue an intercepted request. 



INTERRUPTION HANDLING AND ERROR RECOVERY PROCEDURES 



An I/O interruption alloMS the processor to respond to signals 
from an I/O device Mhich indicate either termination of a phase 
of I/O operations or external action on the device. A complete 
explanation of I/O interruptions is contained in IBM Sv5tem/370 
Principles of Operation . For descriptions of interruption by 
specific devices* refer to IBM publications for each device. 

If error conditions are associated Mith an interruption* the I/O 
supervisor schedules the appropriate device-dependent error 
routine. The channel subsystem is then restarted Mith another 
request that is not related to the channel program in error. 
(The folloMihg paragraphs discuss "related" channel programs.) 
If the error recovery procedures fail to correct the error, the 
system places ones in the first tMO bit positions of the 
DCBIFLGS field of the data control block. You are informed of 
the error by an error code in the event control block. 
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APPENDAGES 



If a channel program depends on the successful completion of a 

previous channel program — as Mhen one channel program retrieves 

data to be used in building another — the previous channel /f \ 

program is called a "related" request. Such a request must be 4^^ 

identified to the EXCP processor. To find out how» see 

"Input/Output Block Fields" on page 95. 

If a permanent error occurs in the channel program of a related 
requests the EXCP processor removes the request queue elements 
for all dependent channel programs from their queue and makes 
them available. 

The related request queue (RRQ) reflects the order in Mhich 
request queue elements are removed from their queue. 

For all requests dependent on the channel program in error » the 
system places completion codes into the event control blocks. 
The DCBIFLGS field of the data control block is also flagged. 
Any requests for a data control block Mith error flags ar& 
posted complete without execution. To reissue requests 
dependent on the channel program in errors you must reset the 
first two bits of the DCBIFLGS field of the data control block 
to zeros. You then reissue EXCP for each channel program 
desired. 

Uith the 3800 > a cancel key or a system-restart-required paper 
jam causes both a lost data indicator to be set in DCBIFLGS and 
a lost page count and channel page identifier to be stored in 
the UCB extension. (See Debuggi ng Handbook and IBM 3800 
Printing Subsystem Programmer's Guide . ) 



An appendage is a programmer-written routine that provides 
additional control over I/O operations. By using appendages^ „ 
you can examine the status of I/O operations and determine the f^ \ 
actions to be taken for various conditions. An appendage may \^' 
receive control when one of the following occurs: 

• EXCP SVC 

• Program controlled interrupt 

• End of extent 

• Channel end 

• Abnormal end 

Appendages get control in supervisor state» receiving the 
following pointers from the EXCP processor J 

• Register 1: Points to the request queue element for the 
channel program. 

• Register 2' Points to the input/output block (lOB). 

• Register 3^ Points to the data extent block (DEB). 

• Register 4: Points to the data control block (DCB). 

• Register 6: Points to the seek address if control is given 
to an end-of-extent appendage. 

• Register 7? Points to the unit control block (UCB). 

• Register 13: Points to a 16-word area you can use to save 
input registers or data. 
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• Register 1^' Points to the location in ths EXGP processor to 
which control is to be returned after execution of an 
appendage. Ulhen returning control to the EXCP processor* 
you may use displacements from the return address in 
register 14. Allowable displacements are summarized in 
Figure 20 and described later for each appendage. 

• Register IS^ Points to the entry point of the appendage. 

The processing done by appendages is subject to these 
requirements and restricti bns- 

• Register 9» if used* must be set to binary zeros before 
control is returned to the system. All other registers* 
except those indicated in the descriptions of each 
appendage* must be saved and restored if they are used. 
Figure 20 summarizes register conventions. 

• No SVC instructions or instructions that change the status 
of the system (for example* WTO* LPSUI* or any privileged 
instructions) can be issued. 

• Loops that test for the completion of I/O operations must 
not be used. 

• Storage used by the I/O supervisor or EXCP processor must 
not be altered. 

The types of appendages are described in the following sections* 
with explanations of when they are created* how they return 
control to the system* and which registers they may use without 
saving and restoring their contents. 



Available Hork Registers^ 

Reg. 10* 11* 12* and 13 
Reg. 10* 11* and 13 
Reg. 10* 11* 12* and 13 
Reg. 10* 11* 12* and 13 

Reg. 10* 11* 12* and 13 



* Certain register conventions for passing parameters from appendages to the EXCP 
processor must be followed. These conventions are described in the individual 
appendage descriptions. 

Figure 20. Entry Points* Returns* and Available Uork Registers for Appendages 
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START-I/0 (SIO) APPENDAGE 

Unless an error recovery procedure is in control* the EXCP 
processor passes control to the SIO appendage just before the 
EXCP processor translates your channel program. 
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Optional return vectors give the I/O requestor the following 
choices: 

Reg. 14+0 \ 

Normal return. Normal channel program translation and 
initiation of I/O. 

Reg. 14+4 

Skip the I/O operation. The channel program is not posted 
complete* but the request queue element is made available. 
You may post the channel program as folloMs: 

1. Save necessary registers. 

2. Put the address of the post routine (found at CVTOPTOl 
in the communications vector table) in register 15. 

3. Place the ECB address from the lOB in register 11. 

4. Set the completion code in register 10. These are the 
four bytes of an ECB. 

5. Go to the post routine pointed to by the CVT, using 
BALR 14,15. 



PROGRAM-CONTROLLED INTERRUPTION (PCI) APPENDAGE 



This appendage is entered at least once if the channel finds one 
or more PCI bits on in a channel program, and may be entered as 
many times as the channel finds PCI bits on. Before the 
appendage is entered, the contents of the channel status Mord 
are placed in the "channel status word" field of the 
input/output block. 

A PCI appendage will be reentered if an error recovery procedure 
is retrying a channel program in which a PCI bit is on. The lOB 
error flag is set when the error recovery procedure is in 
control (lOBFLAGl = X'20'). (For special PCI conditions 
encountered with command retry, see "Channel Programming Notes" 
on page 79.) 

To post the channel program from a PCI appendage, the procedure 
described for the start-I/O appendage is used if the step is 
running ADDRSPC=VIRT or an authorized program is running V=R. 
If the step is running ADDRSPC=REAL and an authorized program 
issued the EXCP request, or SVC 114(EXCPVR) was issued, the PCI 
appendage uses real storage addresses and the following 
procedure is used to post the channel program from the PCI 
appendage. 

1. Put the completion code in register 10 and place X'80* in 
the high-order byte to indicate the key is in register 
(step 5). 

2. Put X*80* in the high-order byte of register 11 and the 
address of the ECB in the low-order bytes. 

3. Put X*80' in the high-order byte of register 12 and the 
address of a BR 14 instruction in the low-order bytes. This 
BR 14 must be in storage addressable from any address space 
(for example, CVTBRET). Note that registers 9 and 14 only 
are restored when you use this option. 

4. Put the address of the ASCB in register 13. 

The next two paragraphs describe how to obtain the ASCB 
address and are followed by sample instructions to 
illustrate the procedure. 

Get the SRB address associated with the I/O operation from 
the RQE field, RQESRB (the RQE address was in register 1 
when the appendage was given control). Get the lOSB address 
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from SRBPARM. From that lOSB, get the identif'. sr field- 
lOSASID. Multiply lOSASID by <». 

Get the pointer to the ASVT (address space vector table) 
found at CVTASVT. The address of the ASCB can be found in 
the ASVT, using the field ASVTENTY-4 indexed by the value 
calculated in the above paragraph. 



USING 


RQE,1 


L 


Y,RQESRB 


USING 


SRBSECT,Y 


LH 


Y, SRBPARM , 


USING 


IOSB,Y 


LH 


Y, lOSASID 
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L 


X,16 


USING 


CVT,X 


L 


X, CVTASVT 


USING 


ASVT,X 


L 


13,ASVTENTY-<KY) 


Note: 




X and Y 


are Mork registers. 






5. Put the requestor's key in register 0. 

6. Put the address of the post routine (found at CVTOPTOl in 
the communications vector table) in register 15. 

7. Go to the post routine using BALR 14»15. Upon return, only 
registers 9 and 14 are valid. For more information on the 
POST routine, see System Programming Library? Supervisor 
Services and Macro Instructions . 

This procedure can be used even if the PCI appendage uses 
virtual storage addresses, but performance may be slightly 
sloMer. 

To return control to the EXCP processor for normal interruption 
processing, use the return address in register 14. 



END-OF-EXTENT (EOE) APPENDAGE 



fj 



This appendage is entered uihen the seek address specified in the 
input/output block is outside the allocated extent limits 
indicated in the data extent block. 

If you use the return address in register 14 to return control 
to the system, the abnormal-end appendage is entered. An 
end-of-extent error code (X'42') is placed in the "ECB code" 
field of the input/output block for subsequent posting in the 
ECB. 

You may use the following optional return addresses? 

• Contents of register 14 plus 4? The channel program is 
posted complete; its request element is returned to the 
available queue. 

• Contents of register 14 plus 8? The request is tried again. 

You may use registers 10 through 13 in an end-of-extent 
appendage without saving and restoring their contents. 

Note: If an end-of-cylinder or file-protect condition occurs, 
the EXCP processor updates the seek address to the next higher 
cylinder or track address, and re-executes the request. If the 
neM seek address is within the data set's extent, the request is 
executed; if the new seek address is not within the data set's 
extent, the end-of-extent appendage is entered. If you wish to 
try the request in the next extent, you must move the new seek 
address to the location pointed to by register 6. 
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If a file protect is caused by a full seek (command code=07} 
embedded Mi thin a channel program* the request is flagged as a 
permanent error» and the abnormal end appendage is entered. 



CHANNEL-END (CHE) APPENDAGE 



This appendage is entered when a channel end (CHE)> unit 

exception (UEX) uith or without channel end> or channel end Mith 

uirong length record (ULR) occurs without any other abnormal-end 
conditions. 

If you use the return address in register 14 to return control 
to the EXCP processor* the channel program is posted complete* 
and its request element is made available. In the case of unit 
exception or wrong length record, the error recovery procedure 
is performed before the channel program is posted complete* and 
the lOBEX flag (X»04') in lOBFLAGl is set on. The CSW status 
may be obtained from the lOBCSM field. 

If the appendage takes care of the wrong length record and/or 
unit exception* it may turn off the lOBEX (X*04*) flag in 
lOBFLAGl and return normally- The svsnt Hill then bs posted 
complete (completion code X*7F* under normal conditions* taken 
from the high-order byte of the lOBECBCC field). If the 
appendage returns normally without resetting the lOBEX flag to 
zero* the request will be routed to the associated device error 
recovery procedure (ERP)* and then the abnormal-end appendage 
will be entered with the completion code in lOBECBCC set to 
X'41' if the ERP could not correct the error. (See Step 1 of 
"Abnormal-End (ABE) Appendage.") 

You may use the following optional return addresses^ 

• Contents of register 14 plus 4: The channel program is not 
posted complete* but its request element is made available. 
You may post the channel program by using the calling 
sequence described under the start-I/0 appendage. This is 
especially useful if you wish to post an ECB other than the 
ECB in the input/output block. 

• Contents of register 14 plus 8^ The channel program is not 
posted complete* and its request element is placed back on 
the request queue so that the I/O operation can be retried. 
For correct re-execution of the channel program* you must 
reinitialize the lOBFLAGl* I0BFLAG2* and I0BFLAG3 fields of 
the input/output block and set the "Error Counts" field to 
zero. As an added precaution* the lOBSENSO* lOBSENSl* and 
lOBCSM fields should be cleared. 

• Contents of register 14 plus 12 i The channel program is not 
posted complete* and its request element is not made 
available. (This return must be used if* and only if* the 
appendage has passed the RQE to the exit effector for use in 
scheduling an asynchronous routine. For information on the 
exit effector* refer to System Programming Library* 
Supervi sor . ) 

You may use registers 10 through 13 in a channel-end appendage 
without saving and restoring their contents. 



ABNORNAL-END (ABE) APPENDAGE 



This appendage may be entered on abnormal conditions* such as* 
unit check* unit exception* wrong length indication* program 
check* protection check* channel data check* channel control 
check* interface control check* chaining check* out-of-extent 
error* and intercept condition (that is* device end error). It 
may also be entered when an EXCP is issued for a request queue 
element that has already been purged. 



^ti/^ 
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1. When this appendage is entered because of a unit exception 
and/or wrong length record indication^ lOBECBCC is set to 
X'41'. For further information on these conditions* see 
*'Channel-End (CHE) Appendage" on page 76. 

2. klhen the appendage is entered because of an out-of-extent 
error, the lOBECBCC is set to X»42'. 

3. Uhen this appendage is entered Mith lOBECBCC set to X*^B'» 
it is because of* 

a. The tape error recovery procedure (ERP) encountering an 
unexpected load point, or 

b. The tape error recovery procedure (ERP) finding zeros in 
the command address field of the CSU. 

4. Uhen the appendage is first entered because of an intercept 
condition, the lOBECBCC is set to X'7E'. If it is then 
determined that the error condition is permanent, the 
appendage Mill be entered a second time Mith the lOBECBCC 
set to X'^^*. The intercept condition signals that an error 
Mas detected at device end after channel end on the previous 
request. 

5. klhen the appendage is entered because of an EXCP being 
issued to an already purged request queue element, this 
request Mill enter the abnormal end appendage Mith the 
lOBECBCC set to X*^8*. This applies only to related 
requests. 

6. If the appendage is entered Mith lOBECBCC set to X»7F», it 
may be because of a unit check, program check, protection 
check, channel data check, channel control check, interface 
control check, or chaining check. If the lOBECBCC is X'7F', 
it is the first detection of an error in the associated 
channel program. If the lOBEX flag (bit 5 of the lOBFLAGl) 
is on, the lOBECBCC field Mill contain a 41, 42, 48, 4B, or 
4F in hexadecimal, indicating a permanent I/O error. 

To determine if an error is permanent, you should check the 
lOBECBCC field of the lOB. To determine the type of error, 
check the channel status Mord field and the sense information in 
the lOB. HoMever, Mhen the lOBECBCC is X'42', X»48', or X»4F*, 
these fields are not applicable. For X'44*, the CSW is 
applicable, but the sense is valid only if the unit check bit is 
set. 

If you use the return address in register 14 to return control 
to the system, the channel program is posted complete, and its 
request element is made available. You may use the folloMing 
optional return addresses^ 

• Contents of register 14 plus 4^ The channel program is not 
posted complete, but its request element is made available. 
You may post the channel program by using the calling 
sequence described under the start-I/0 appendage. 

• Contents of register 14 plus 8^ The channel program is not 
posted complete, and its request element is placed back on 
the request queue so that the request can be retried. For 
correct reexecution of the channel program, you must 
reinitialize the lOBFLAGl, I0BFLAG2, and I0BFLAG3 fields of 
the input/output block and set the lOBERRCT field to zero. 
As an added precaution, the lOBSENSO, lOBSENSl, and tOBCSU 
fields should be cleared. 

• Contents of register 14 plus 12 J The channel program is not 
posted complete, and its request element is not made 
available. (This return must be used if, and only if, the 
appendage has passed the RQE to the exit effector for use in 
scheduling an asynchronous routine.) 
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You may use registers 10 through 13 in an abnormal-end appendage 
without saving and restoring their contents. 



HAKING YOUR APPENDAGES PART OF THE SYSTEM 



Before your appendages can be executed^ they must become members 
of either the SYSl.LPALIB or SYSl.SVCLIB data set. There are 
two ways to put appendages into SYSl.LPALIB or SYSl.SVCLIB: ^hey 
can be included at system generation using the DATASET macrol 
instruction (a full explanation appears in System Generation 
Reference ) > or they can be link-edited into SYSl.LPALIB or 
SYSl.SVCLIB after the system has been generated. Each appendage 
must have an 8-character member name» the first six characters 
being IGG019» the last two being anything in the range from UA 
to Z9. Note> however » if your program runs in a V=R address 
space and uses a PCI appendage^ the PCI appendage and any 
appendage that the PCI appendage refers to must be placed in 
either SYSl.SVCLIB or the fixed link pack area (LPA). For 
information on providing a list of programs to be fixed in 
storage* see System Programming Library: Initialization and 
Tuning . 



THE AUTHORIZED APPENDAGE LIST (ZEAAPPOO) 



If an "unauthorized" program opens a DCB to be used with an EXCP 
macro instruction* the names of any appendages associated with 
the DCB must be listed in the lEAAPPOO member of SYSl .PARMLIB. 
(An "unauthorized" program is one that runs in a protection key 
greater than 7 and has not been marked as authorized by the 
Authorized Program Facility.) 

If your appendages were put in SYSl.LPALIB or SYSl.SVCLIB at 
system generation* their names are automatically put in 
lEAAPPOO. If your appendages were added to SYSl.LPALIB or 
SYSl.SVCLIB after system generation, you can add lEAAPPOO to 
SYSl. PARMLIB and put the names of the appendages in it in one 
job step with the lEBUPDTE utility. 

Here i s an example of JCL statements and lEBUPDTE input that 
will add lEAAPPOO to SYSl. PARMLIB and put the names of one EOE 
appendage* two SIO appendages* two CHE appendages* and one ABE 
appendage in lEAAPPOO: 



// 


JOB 


• • • 


// 


EXEC 


PGM=IEBUPDTE 


//SYSPRINT 


DD 


SYSOUT=A 


//SYSUT2 


DD 


DSN=SYS1. PARMLIB* DISP=OLD 


//SYSIN 


DD 


X 


,/ 


ADD 


NAME=IEAAPPOO*LIST=ALL 


EOEAPP UA* 






SIOAPP X1*X2* 






CHEAPP Z3,24* 






ABEAPP Z2 






/X 







Note the following about the lEBUPDTE input: 

• The type of appendage is identified by six characters that 
begin in column 1. EOEAPP identifies an EOE appendage* 
SIOAPP an SIO appendage* CHEAPP a CHE appendage* and ABEAPP 
an ABE appendage. (The PCI appendage identifier* PCIAPP* is 
not shown* because the example adds no PCI appendage name to 
lEAAPPOO.) 

• Only the last two characters in an appendage's name are 
specified* beginning in column 8. 

• Each statement that identifies one or more appendage names 
ends in a comma* except the last statement. 
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You can also use lEBUPDTE to add appendage names later or delete 
appendage names. Here i s an example of JCL statements and 
lEBUPDTE input that adds the names of a PCI and an ABE appendage 
to the lEAAPPOO appendage list that Mas created in the preceding 
example* and deletes the name of an SIO appendage from that 
list: 



// 




JOB 


// 




EXEC 


//SYSPRIN7 




DD 


//SYSUT2 




DD 


//SYSIN 




OD 


./ 




REPL 


PCIAPP Yl, 






EOEAPP WA, 






SIOAPP XI, 


X2, 




CHEAPP Z3, 


Z^, 




ABEAPP Z2, 


Z4 




/x 







PGM=IEBUPDTE 

SYSOUT=A 

DSN=SYS1.PARMLIB,DISP=0LD 

M 

NAnE=IEAPPOO,LIST=ALL 



Note the following about the lEBUPDTE input: 

• The command to lEBUPDTE in this case is REPL (replace). 

• All the appendage names that Br& to remain in lEAAPPOO are 
repeated. 

• IGG019Z4 is both a CHE and an ABE appendage. 



CHANNEL PR06RAMHING NOTES 






o 



Command retry is a function of the channel supporting the 2305» 
3330/3333, 33^0/3344, 3350, 3375, and 3380 direct access 
devices. Uhen the channel subsystem receives a retry request, 
it repeats the execution of the CCU requiring no additional 
input/output interrupts. For example, a control unit may 
initiate a retry procedure to recover from a transient error. 

A command retry during the execution of a channel program may 
cause any of the folloMing conditions to be detected by the 
initiating program: 

• Modifying CCUs: A CCU used in a channel program must not be 
modified before the CCM operation has been successfully 
completed. Uithout the command retry function, a command 
Mas fetched only once from storage by a channel. Therefore, 
a program could determine through condition codes or program 
controlled interruptions (PCI) that a CCW had been fetched 
and accepted by the channel. This permitted the CCU to be 
modified before reexecution. Uith the command retry 
function, this cannot be done, because the channel Mill 
fetch the CCU from storage again on a command retry 
sequence. In the case of data chaining, the channel Mill 
retry commands starting Mith the first CCU in the data 
chain. 

• Program Controlled Interrupts: A CCU containing a PCI flag 
may cause multiple program controlled interrupts to occur. 
This happens if the PCI-f lagged CCU Mas retried during a 
command retry procedure, and a PCI could be generated each 
time the CCU is reexecuted. 

• Residual Count: If a channel program is prematurely 
terminated during the retry of a command, the residual count 
in the channel status Mord (CSU) Mill not necessarily 
indicate hoM much storage Mas used. For example, if the 
control unit detects a "Mrong length record" error 
condition, an erroneous residual count is stored in the CSU 
until the command retry is successful. Uhen the retry is 
successful, the residual in the CSU reflects the correct 
length of the data transfer. 
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Command Address: klhen data chaining Mith command retry» the 

CSU may not indicate houi many CCUIs have been executed at the jr~^ 

time of a PCI. For example^ (f \ 



CCU9 Channel Program 

1 Read» data chain 

2 Ready data chain 

3 Ready data chains PCI 
^ Ready command chain 

In this example, assume that the control unit signals 
command retry on Read ff3 and the CPU accepts the PCI after 
the channel resets the command address to Read ftl because of 
command retry. The CSW stored for the PCI will contain the 
command address of Read ftly when actually the channel has 
progressed to Read #3. 

Testing Buffer Contents on Data Read^ Any program that tests 
a buffer to determine when a CCU has been executed and 
continues to execute based on this data may get incorrect 
results if an error is detected and the CCU is retried. 



HACRO SPECIFICATIONS FOR USE HUH EXCP 



If you are using the EXCP macro instruction, you must also use 
DCB, OPEN, CLOSE, and, in some cases, the EOV macro instruction. 
The parameters of these macro instructions and the EXCP macro 
instructions are explained here. A diagram of the data control 
block is included Mith the description of the DCS macro 
i nstruct ion. 



DCB — DEFINE DATA CONTROL BLOCK FOR EXCP 



>A y 



The EXCP form of the DCB macro instruction produces a data pT ^ 
control block that can be used with the EXCP macro instruction. \^ 
You must issue a DCB macro instruction for each data set to be 
processed by your channel programs. Notation conventions and 
format illustrations of the DCB macro instruction are given in 
Data Management Macro Instructions . DCB parameters that apply 
to EXCP may be divided into four categories, depending on the 
following portions of the data control block that are generated 
when they are specified^ 

• Foundation block. This portion is required and is always 12 
bytes in length. You must specify two of the parameters in 
this category. 

• EXCP interface. This portion is optional. If you specify 
any parameter in this category, 20 bytes are generated. 

• Foundation block extension and common interface. This 
portion is optional and is always 20 bytes in length If this 
portion is generated, the device-dependent portion is also 
generated. 

• Device dependent. This portion is optional and is generated 
only if the foundation block extension and common interface 
portion is generated. Its size ranges from 4 to 20 bytes, 
depending on specifications in the DEVD parameter. However, 
if you do not specify the DEVD parameter (and the foundation 
extension and common interface portion is generated), the 
maximum 20 bytes for this portion are generated. 

Some of the procedures performed by the system when the data 
control block is opened and closed (such as writing file marks 
for output data sets on direct access volumes) require 
information from optional data control block fields. You should 
make sure that the data control block is large enough to provide 
all information necessary for the procedures you want the system 
to handle. 
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Figure 21 on page 82 shouis the relative position of each portiere 
of an opened data control block. The fields corresponding to 
each parameter of the DCB macro instruction are also designated^ 
Mith the exception of DDNAME^ which is not included in a data 
control block that has been opened. The fields identified in 
parentheses represent system information that is not associated 
with parameters of the DCB macro instruction. 

Sources of information for data control block fields other than 
the DCB macro instruction are data definition (DD) statements^ 
data set labels^ and data control block modification routines. 
You may use any of these sources to specify DCB parameters. 
However^ if a particular portion of the data control block is 
not generated by the DCB macro instruction^ the system does not 
accept information intended for that portion from any 
alternative source. 

You may provide symbolic names for the fields in one or more 
EXCP DCBs by coding a DCBD macro to generate a dummy control 
section (DSECT). To map the common interface, foundation block 
extension, and foundation block, you code DSORG=XE. To map the 
foundation block and EXCP interface, you code DSORG=XA. You may 
code DSORG=(XA,XE) to map both. For further information, see 
Data Management Macro Instructions . 



Foundation Block Parameters 



*X 



DDNAME= symbol 

The name of the data definition (DD) statement that 
describes the data set to be processed. This parameter 
must be given. 

MACRF=(E) 

The EXCP macro instruction is to be used in processing the 
data set. This operand must be coded. 

REPOS={Y|N} 

Magnetic tape volumes* This parameter indicates to the 
dynamic device reconfiguration (DDR) routine whether the 
user is keeping an accurate block count. If the user is 
keeping an accurate block count, the DDR routine can 
attempt to swap the volume. (You must maintain the block 
count in the DCBBLKCT field.) 

Y — The user is keeping an accurate block count and the DDR 
routine can attempt to swap the volume. 

N — The block count is unreliable and the DDR routine cannot 
and will not attempt to swap the volume. 

If the operand is omitted, N is assumed. 



EXCP Xnterface Parameters 



EOEA= symbol 

2-byte identification of an EOE appendage that you have 

entered into SYSl.LPALIB or SYSl.SVCLIB. 

PCI A= symbol 

2-byte identification of a PCI appendage that you have 

entered into SYSl.LPALIB or SYSl.SVCLIB. 

SIOA= s ymbol 

2-byte identification of a SIO appendage that you have 

entered into SYSl.LPALIB or SYSl.SVCLIB. 



CENDA= symbol 

2-byte identification of a CHE appendage that you have 
entered into SYSl.LPALIB or SYSl.SVCLIB. 
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The device— dependent portion of the data control 
block varies in length and format according to 
specifications in the DSORG and DEVD parameters. 



Illustrations of this portion for each device 
type are included in the description of the DEVD 
parameter. 


20 

BUFNO 


BUFCB 


24 

BUFL 


DSORG 


28 

lOBAD 


BFALN 


EODAD 


36 

RECFM 


EXLST 


40 

(TIOT) 


MACRF 


44 

(IFLGS) 


(DEB Address) 


48 

(OFLGS) 


Reserved 


52 

OPTCD 


Reserved 


56 

Reserved 


60 

EOEA 


PCIA 


64 

SIOA 


CENDA 


68 

XENDA 


Reserved 



1 

> 

J 
1 

> 

J 

"I 

> 

J 
1 

> 

J 






Device 
Dependent 



Common 
Interface 



Foundation 

Block 

Extension 



Foundation 
Block 






EXCP 
Interface 



Figure 21. Data Control Block Format for EXCP (After OPEN) 



XENDA= symbol 

2-byte identification of an 
entered into SYSl.LPALIB or 



ABE appendage 
SYSl.SVCLIB. 



that you have 



OPTCD=Z 

indicates that* for magnet 
error recovery procedure ( 
data check is encountered. 
Mhen the tape i s knoMn to 
application does not requi 
Its proper use Mould inclu 
the SYNAD routine. Specif 
also cause generation of a 
This parameter is ignored 
generation. 



ic tape (input only)* a reduced 
5 reads only) Mill occur Mhen a 

It should be specified only 
contain errors and the 
re that all records be processed, 
de error frequency analysis in 
i cat ion of this parameter Mill 

foundation block extension, 
unless it Mas selected at system 
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IMSK= value 

Any specification indicates that the system Mill not use 
IBN-supplied error routines. 



Foundation Block Extension and common interface Parameters 

EXLST= address 



- aggress 

the address of an exit list that you have Nritten for 
exception conditions. The format of this exit list is 
given in Data Management Services . 

EODAD=address 

the address of your end-of-data-set routine for input data 
sets. If this routine is not available Mhen it is 
required* the task is abnormally terminated. 

DSORG=€PS|PO|DA|IS} 

the data set organization (one of the following codes). 
Each code indicates that the format of the device-dependent 
portion of the data control block is to be similar to that 
generated for a particular access method: 

Code DCB Format for 



PS 


QSAM or BSAM 


PO 


BPAM 


DA 


EDAM 


IS 


QISAM or BISAM 






o 



For direct access devices* if you specify PS or PO, you 

must maintain the follouing fields of the device-dependent 

portion of the data control block so that the system can 
Mrite a file mark for output data sets: 

• The track balance (DCBTRBAL) field* Mhi'ch contains a 
2-byte binary number that indicates the remaining 
number of bytes on the current track. This number can 
be obtained from the system track algorithm routine. 

• The full disk address (DCBFDAD) field* which indicates 
the location of the current record. The address is in 
the form MBBCCHHR. 

These fields are written into the format-1 DSCB and are 
used by Open routines for staging MSS data sets. Staging 
is done only up through the last cylinder specified by 
these fields if the data set is reopened for OUTPUT* INOUT, 
OUTIN, OUTINX, or EXTEND. 

If you specify PO for a direct access device* the DCBDIRCT 
field Mill not be updated. Therefore* you should be 
careful when using EXCP with the STOU macro. 

IOBAD= address 

the address of an input/output block (lOB). If a pointer 
to the current lOB is not required* you may use this field 
for any purpose. 

The folloMing parameters are not used by the EXCP routines. 
They provide additional information that the system Mill store 
for later use by access methods that read or update the data 
set. 

RECFH=cod£ 

. the record format of the data set. Record format codes are 
given in Data Management Macro Instructions . Ulhen writing 
a data set to be read later* RECFM* LRECL* and BLKSIZE 
should be specified to identify the data set attributes. 
LRECL and BLKSIZE can only be specified in a DD statement* 
because these fields do not exist in a DCB used by EXCP. 
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BFTEK=CS|E} 

the buffer technique^ either simple or exchange. 

BFALN=CF|D} 

the Mord boundary alignment of each buffer » either fullMord 
or doubleMord. 

BUFL= lenqth 

the length in bytes of each buffer; the maximum length is 
32,767. 

BUFNO=nutnber 

the number of buffers assigned to the associated data set; 
the maximum number is 255. 

BUFCB=address 

the address of a buffer pool control block, that is, the 
8-byte field preceding the buffers in a buffer pool. 



o 



Device-Dependent Parameters 



DEVD=code 

the device on Mhich the data set may reside. The codes are 
listed in order of descending space requirements for the 
data control block: 



Code Device 

DA Direct access 

TA Magnetic tape 

PT Paper tape 

PR Printer 

PC Card punch 

RD Card reader 

Note: For MSS virtual volumes, DA should be used. 

If you do not Mish to select a specific device until job setup 
time, you should specify the device type requiring the largest 
area; that is, DEVD=DA. 

The following diagrams illustrate the device-dependent portion 
of the data control block for each combination of device type 
specified in the DEVD parameter and data set organization 
specified in the DSORG parameter. Fields that correspond to 
device-dependent parameters in addition to DEVD are indicated by 
the parameter name. For special services, you may have to 
maintain the fields shouin in parentheses. The special services 
are explained in the note that folloMs the diagram. 

Device-dependent portion of data control block when DEVD=DA and 
DSORG=PS: 



4 

Reserved 


5 

DCBFDAD 




8 






13 

DCBDVTBL 


16 

DCBKEYLE 


17 

DCBDEVT 


18 

DCBTRBAL 



o 
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For output data sets» the system uses the contents of the full 
disk address (DCBFDAD) field plus one to Mrite a file mark Mhen 
the data control block is closed, provided the track balance 
(DCBTRBAL) field indicates that space is available. If DCBTRBAL 
is less than &, the file mark is written on the next sequential 
track. You must maintain the contents of these two fields 
yourself if the system is to write a file mark. OPEN will 
initialize DCBDVTBL and DCBDEVT. 

Device-dependent portion of data control block when DEVD=DA and 
DS0RG=DA: 



16 

DCBKEYLE 


18 

Reserved 



Device-dependent portion of data control block when DEVD=TA and 
DSORG=PS: 



12 

DCBBLKCT 


16 
DCBTRTCH 


17 

Reserved 


18 

DCBDEN 


19 

Reserved 






The system uses the contents of the block count (DCBBLKCT) field 
to write the block count in trailer labels when the data control 
block is closed or when the EOV macro instruction is issued. 
You must maintain the contents of this field yourself if the 
system is to have the correct block count. (Note: The I/O 
supervisor increments this field by the contents of the lOBINCAM 
field of the lOB at the completion of each I/O request.) 

Mhen using EXCP to process a tape data set open at a checkpoint # 
you must be careful to maintain the correct count; otherwise* 
the system may position the data set incorrectly when restart 
occurs. If REPOS=Y, the count must be maintained by you for 
repositioning during dynamic device reconfiguration. 

Device-dependent portion of data control block when DEVD=PT and 
DSORG=PS: 



16 

DCBCODE 


18 

Reserved 



Device-dependent portion of data control block when DEVD=PR and 
DSORG=PS: 



16 

DCBPRTSP 


18 

Reserved 



Device-dependent portion of data control block when DEVD=PC or 
RD and DSORG=PS: 



^l^ij^ 



16 

DCBMODE,DCBSTACK 


IS 

Reserved 



The following DCB operands pertain to specific devices and may 
be specified only when the DEVD parameter is specified. 
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KEYLEN=length 

for direct access devices^ the length in bytes of the key 
of a physical record* Mith a maximum value of 255. Uhen a 
block is read or written* the number of bytes transmitted 
i s the key length plus the record length. 

CODE=value 

for paper tape* the code in Mhich records are punched* 

Value Code 

I IBM BCD 

F Friden 

B Burroughs 

C National Cash Register 

A ASCII 

T Teletype (trademark of Teletype Corporation) 

N No conversion (format-F records only) 

If this parameter is omitted* N is assumed. 

DEN=value 

for magnetic tape* the tape recording density in bits per 
inchJ 

Value: Density: 

7-track tape device 9^track tape device 

1 556 — 

2 800 800(NRZI) 

3 — 1600(PE) 

4 — 6250(GCR) 

NRZI — Non-return-to-zero change to ones recording 
PE — phase encoded recording 
GCR — group coded recording 

If this parameter is omitted* the highest density available 
on the device is assumed. 

TRTCH=value 

for 7-track magnetic tape* the tape recording technique^ 

Value Tape Recording Technique 

C Data conversion feature is available. 

E Even parity is used. (If omitted* odd parity is 

assumed. ) 
T BCDIC to EBCDIC translation is required. 

MODE=value 

for a card reader or punch* the mode of operation. Either 
C (column binary mode) or E (EBCDIC code) may be specified. 

STACK=value 

for a card punch or card reader* the stacker bin to receive 
cards* either 1 or 2. 

PRTSP=value 

for a printer* the line spacing* either 0* 1* 2* or 3. 



DSORG Parameter of the DCBD Macro 



In addition to the operands described in Data Management Macro 
Instructions for the DSORG parameter of the DCBD macro* you may 
specify the follouing operands. 



DSORG= 



XA specifies a DCB Mith the EXCP interface section 
(including appendage names) 



o 
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XE specifies a DCB Mith the foundation block extension 
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OPEN — ZNZTZALZZE DATA CONTROL BLOCK 



The OPEN macro instruction initializes one or more data control 
blocks so that their associated data sets can be processed. You 
must issue OPEN for all data control blocks that are to be used 
by your channel programs. (A dummy data set may not be opened 
for EXCP.) Some of the procedures performed Mhen OPEN is 
executed are: 

Reading in the JFCB (job file control block) » unless the 
TYPE=J option of the macro instruction was coded 

Construction of the data extent block (DEB) 

Transfer of information from the JFCB and data set labels to 
the DCB 

Verification or creation of standard labels 

Tape positioning 

Loading of your appendage routines 

The parameters of the OPEN macro instruction are' 



[symbol] 


OPEN 


(deb address 

f [(options)]* . . . ) 



deb address — A-tvpe address or (2-12) 

the address of the data control block to be initialized. 
(More than one data control block may be specified.) 

optionl 

the intended method of I/O processing of the data set. You 
may specify this parameter as either INPUT, RDBACK, OUTPUT, 
or EXTEND. For magnetic tape, label processing for each of 
these Mhen OPEN is executed is as follows: 

INPUT Header labels are verified. 

RDBACK Trailer labels are verified. 

OUTPUT Header labels are created. 

EXTEND Header labels are created. 

If this parameter is omitted, INPUT is assumed. 

option2 

the volume disposition that is to be provided when volume 
switching occurs. The operand values and meanings are as 
follows: 

REREAD Reposition the volume to process the data set 
again. 

LEAVE No additional positioning is performed at 
end-of-volume processing. 

DISP Specifies that a tape volume is to be disposed of 
in the manner implied by the DD statement 
associated with the data set. Direct access volume 
positioning and disposition are not affected by 
this parameter of the OPEN macro instruction. 
There are several dispositions that can be 
specified in the DISP parameter of the DD 
statement: 

DISP=PASS, DELETE, KEEP, CATLG, or UNCATLG. Only 
DISP=PASS has significance at the time an 
end-of-volume condition is encountered. The 
end-of-volume condition may result from the 
issuance of an FEOV macro instruction or may be the 
result of reaching the end of a volume. 
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If DISP=PASS was coded In the DD statement* the 
tape Mill be spaced forward to the logical end of 
the data set on the current volume. 

If a DISP option other than DISP=PASS is coded on 
the DD statement y the action taken when an 
end-of-volume condition occurs depends (1) on how 
many tape units are allocated to the data set and 
(2) on how many volumes are specified for the data 
set in the DD statement. This is determined by the 
UNIT= and VOLUME= operands of the DD statement 
associated with the data set. If the number of 
volumes is greater than the number of units 
allocated* the current volume will be rewound and 
unloaded. If the number of volumes is less than or 
equal to the number of units* the current volume is 
merely rewound. 

If you intend to process a multi volume direct data set* you must 
cause open routines to build a data extent block for each volume 
and issue mount messages for them. This can be done by reading 
in the JFCB with a RDJFCB macro instruction and opening each 
volume of the date Est. Tha follow: ng code i Il'-:::tr5tc3 the 
procedure: 



o 
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^"*\, 
^L**^ 





RDJFCB 


DCBl 




SR 


R3,R3 


X 






x 








IC 


R3,JFCBNV0L 


X 








LA 


R<»,DCB1 



X 

LOOP 

X 



READS IN THE JFCB 
CLEARS REG 3; IT MILL 
HOLD COUNT OF VOLS TO 
BE OPENED 
PUTS » OF VOLS 
IN REG 3 

R4 POINTS TO DCB FOR 
VOL TO BE OPENED 
PUTS SEQUENCE # OF 
FIRST VOL TO BE 
OPENED IN REG 5 

PUTS SEQ ft OF VOL 
TO BE OPENED WHERE 
OPEN RTNS LOOK 

OPEN ((R4), OUTPUT) »TYPE=J OPENS ONE VOL 
NOTE THAT THE TYPE=J OPTION OF THE MACRO MUST BE USED 

LA R4,DCB2-DCB1(R4) INCREMENT REG 4 TO 

POINT TO THE DCB FOR 
THE NEXT VOL TO BE 
OPENED 

LA R5,1(R5) INCREMENT TO SEQ ft OF 

NEXT VOL TO BE OPENED 

BCT R3,L00P LOOP UNTIL ALL VOLS 

OPEN 



LA 



EQU 
STH 



R5,l 



R5,JFCBVLSQ 



O 



JFCB DS 

ORG 
JFCBVLSQ DS 

ORG 
JFCBNVOL DS 

ORG 
X MAPPING MACRO 
DCBl DCB DDNAME= 
DCB2 DCB DDNAME= 
DCB3 DCB DDNAME= 
DCB4 DCB DDNAME= 
DCB5 DCB DDNAME= 
X THIS PROCEDURE 
X EXTENSION, WHI 
X BE READ IN 
EXITS DS 

DC 



CL176 

JFCB+70 

H 

JFCB+117 
FLl 

lEFJFCBN MAY 

SYSUT1,MACRF= 

SYSUT1,MACRF= 

SYSUT1,MACRF= 

SYSUT1,MACRF= 

SYSUT1,MACRF= 

WORKS FOR 5 
CH IDENTIFIES 



JFCB READ IN HERE 

SEQ ft OF VOL TO BE 
OPENED 

ft OF VOLS IN DATA SET 

ALSO BE USED 
(E),EXLST=EXITS,DSORG=PS 
(E),EXLST=EXITS,DSORG=PS 
( E) , EXLST=EXITS, DSORG=PS 
( E) , EXLST=EXITS, DSORG=PS 
(E),EXLST=EXITS,DSORG=PS 
VOLS OR LESS; THE JFCB 
ADDITIONAL VOLS, CAN'T 



OF 
X'87',AL3(JFCB) 



87 IDENTIFIES THIS AS 
THE EXIT LIST ENTRY 
THAT SHOWS WHERE JFCB 
WILL BE READ IN 



Use of the RDJFCB macro instruction and the OPEN macro 
instruction Mith the TYPE=J option is explained in detail under 
"Reading and Modifying a Job File Control Block" on page 144. 



EXCP— EXECUTE CHANNEL PROGRAM 



The EXCP macro instruction requests the initiation of the I/O 
operations of a channel program. You must issue EXCP whenever 
you want to execute one of your channel programs. The format of 
the EXCP macro instruction is? 



^^\ 
%/ 



[symbol] 


EXCP 


iob-address 



iob-address — A-tvpe address, (2-12), or (1) 

the address of the input/output block of the channel 
program to be executed. 
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ATLAS'— ASSIGNING AN ALTERNATE TRACK AND COPYING DATA FROM THE DEFECTIVE TRACK 

A program that uses the EXCP macro instruction for input and 
output and is APF authorized may use the ATLAS macro 
instruction* during the execution of the program* to obtain an 
alternate track and to copy a defective track onto the alternate 
track. With the use of ATLAS* the program can recover from 
permanent (hard) errors encountered in the execution of the 
folloMing types of I/O commands: 

• Search ID. 

• Mrite. (The error condition must be confirmed during the 
execution of the channel program by a CON that checks the 
data written. ) 

• Read count. Errors in the CCHHR part of the count area can 
be recovered from unless the record is the home address or 
record zero. Errors in the KDD part of the count area 
cannot be recovered from unless the user has identified the 
defective record. 

Note! ATLAS may be used for all direct access devices with the 
exception of MSS volumes (3330V). 

Your DOB must include the DCBRECFM field* and the field must 
show whether the data set is in the track overflow format. If 
it is* recovery from errors in last records on tracks depends on 
your identifying the track overflow record segments. 

Recovery takes the form of obtaining a good alternate track and 
copying the defective track onto the good alternate one. Unless 
a reexecution of the channel program by ATLAS can correct the 
defect* the user should examine* and if necessary replace* 
defective records in a subsequent job if the data set is to be 
processed again. 

The format is: 



[ svmbo 1 ] 


ATLAS 


PARHADR=Caddress} 
E,CHANPRG={:R def.lNR^l 

i,cntptr=cpTf}1 
[>urits=<:yes|no}] 



PARHADR 

Address of a parameter address list of the following 
format: 



Address of lOB for the channel program that 
encountered the error 



Address of count area field 



O 
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The count area field contains the CCHHRKDD of a defective 
record or the CCHH of a track that is to be copied. 

address — A-tvpe address* (2-12) > or (1) 

CHANPRG=CR|NR1 

specifies whether the channel program that encountered the 
error can be executed again. 

R Channel program may be executed again by ATLAS. 

Before permitting reexecution of the channel program 
by ATLAS* you must reset the error indications of the 
previous execution fields in the DCBIFLGS. (See the 
example of the use of ATLAS beloM.) 



NR 



Channel program may not be executed again. 



If this parameter is omitted* R is assumed. 

CNTPTR 

specifies whether the count area field contains a full 
count area (CCHHRKDD) or a partial count area (CCHH). 

P Part of the count area (the CCHH address of the track 
to be copied). 

F Full count area (CCHHRKDD count of the record that was 
found defective). 

If this parameter is omitted* P is assumed. 



MRUS 



#*\^ 

^l^' 



track overflow segment identification. 

If your data set is in the track overflow format, this 
identification determines recovery from errors in last 
records on tracks. 

YES If this is the last record on the track, it is a 
segment other than the last of a track overflow 
record. 

NO If this is the last record on the track* it is the 
last or only segment of a track overflow record. 



Using ATLAS 



If this parameter is omitted* it is assumed that it cannot 
be established whether a last record is a segment of an 
overflow record. 



If a channel program encounters a unit check condition (shown in 
the CSW) in its execution* the EXCP Processor program will 
place the sense bytes in the lOB. ATLAS can be used to recover 
from sense conditions shown by the following bit settings^ 
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lOBSENSO X»08' Data check 

lOBSENSl X'80' Permanent 

lOBSENSl X*02' Missing address marker (see the follouiing 

for combinations of this bit setting 
Nhich ATLAS cannot handle). 

HoMever» defects in the home address record or the record zero 
record cannot be recovered from through the use of ATLAS. These 
conditions are shouin by: 

lOBSENSl X'OZ* and lOBSENSO X'Ol' — home address defect. 

lOBSENSl X*OA' — record zero defects or» home address cannot 
be located. 

Also» before using ATLAS» you must reset error indications as 
follows' 

NX DCBIFLGS,X'3F* Reset the DCBIFLGS error indications. 

The ATLAS program Mill attempt to find a good alternate track 
and Mill attempt to copy the defective track onto the good 
track, including all error conditions in either key or data 
areas. The error conditions may be rectified by reexecuting the 
channel program or through the use of the lEHATLAS utility 
program in a subsequent step. 

Example^ The following illustrates the use of the ATLAS macro 
instruction. 





EXCP 


MYIOB 






WAIT 


ECB=MYECB 






TM 


MYECB,X»7F» 


TEST FOR I/O ERROR 




BO 


NEXT 


NO, SUCCESSFUL, GO TO 


X 






ANOTHER ROUTINE 




TM 


IOBCSW+3,X»02' 


UNIT CHECK 




BZ 


OTHER 


NO, DO OTHER ERROR 


X 






PROCESSING 




TM 


lOBSENSO, X»08' 


DATA CHECK 




BNO 


OTHER 


NO, CAN'T HANDLE 




TM 


lOBSENSl, X'80' 


PERMANENT 




BNO 


OTHER 


NO, CAN'T HANDLE 




NI 


DCBIFLGS, X'3F' 


RESET ERROR 


H 






INDICATORS 




ATLAS 


PARMADR=THERE,i 


CHANPRG=R 



Operation of the ATLAS Program 

The ATLAS program (SVC 86): 



Establishes the availability and address of the next 
alternate track from the format-^ DSCB of the VTOC. 

Brings all count fields from the defective track into 
storage to establish the description of the track. 

Initializes the alternate track. (Urites the home address 
and record zero.) 

Brings the key and data areas of each record into storage, 
one at a time, and combines them Mith their new count area 
to write the complete record onto the alternate track. 

Uhen the copying is finished, chains the alternate to the 
defective track and updates the VTOC. 
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Control IS returned to your program at the next executable 
instruction folloMing the ATLAS macro instruction. The success 
of the ATLAS macro instruction can be determined by examining 
the contents of register 15» Mhich Mill contain one of the 
return codes described beloM. If register 15 contains decimal 
0» 36> 40> or 44> the contents of register may be significant. 

Code Meaning 

0(00) Successful completion. Key and data areas have been 
copied from the defective track onto a good alternate 
one. The only error encountered Mas in the record 
identified by the user's CCHHRKDD value. 

If the channel program is reexecutable» it has been 
successfully reexecuted. 

4(04) This device type does not have alternate tracks that 
can be assigned by programming. 

8(08) All alternate tracks for the device have been assigned. 

12(0C) A request for storage (GETMAIN macro instruction) could 
not be satisfied. 

16(10) All attempts to initialize and transfer data to an 

alternate track failed. The number of attempts made is 
equal to 10% of the assigned alternates for the device. 

20(14) The type of error shoMn by the sense byte cannot be 

handled through the use of the ATLAS macro instruction. 
The condition is other than a data check (in the count 
or data areas) or a missing address marker. 

24(18) The format-4 DSCB of the VTOC cannot be read; therefore 
alternate track information is not available to ATLAS. 

28(1C) The record specified by the user was the format-4 DSCB 
and it could not be read. 

32(20) An error found in count area of last record on the 

track cannot be handled because last-record-on-track 
identification is not supplied. 

36(24) An error Mas encountered Mhen reading or Mriting the 

home address record or record zero. No error recovery 

has taken place. If register contains 

X*01 00 00 00% the defect is in record zero. 

40(28) Successful completion. Key and data areas have been 
copied from the defective track onto a good alternate 
one. HoMever* the alternate track may have records 
Mi th defective key or data areas. Register 
identifies the first three found defective as folloMS? 

n R R R 

n — The number of record numbers that folloM (0, 1, Z, 
or 3). 

R — The hexadecimal number of the record found defective 
but copied anyway. 

If the channel program is reexecutable» it has been 
successfully reexecuted. 

44(2C) Errors encountered and no alternate track has been 

assigned. The return parameter register (register 0) 
will contain the R of a maximum of three error records. 



'1 L' 
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EOV — END OF VOLUME 



%J 



Error conditions that return this code are? 

1. ATLAS received an error indication for a record 
Mith a data length in the count field of zero. 
Recovery Mas not possible because a distinction 
cannot be made betuieen an EOF record and an invalid 
data length. 

2. An error occurred Nhile reading the count field of 
a record and the KDD (key length-data length) uas 
found to be defective. 

3. More than three records on the specified track 
contained errors in their count fields. 

48(30) No errors found on the tracks no alternate assigned. 
ATLAS Mill not assign an alternate unless a track has 
at least one defective record. 

52(34) I/O error in reexecuting user's channel program. A 
good alternate is chained to the defective track and 
data has been transferred. The user's control blocks 
Mill give indication of thsi error condition causing 
failure in reexecution of the channel program. 

56(38) The DCB reflects a track overfloM data set» but the UCB 
device type shoMS that the device does not support 
track overfloM. 

60(3C) The CCHH of the user-specified count area is not Mi thin 
the extents of the data set. 

64(40) The device is an MSS virtual device^ Mhich is not 
supported. 



The EOV macro instruction identifies end-of-volume and 
end-of-data-set conditions. For an end-of-volume condition^ EOV 
causes SMitching of volumes and verification or creation of 
standard labels. For an end-of-data-set condition, EOV causes 
your end-of-data set routine to be entered. Before processing 
trailer labels on a tape input data set» you must decrement the 
DCBBLKCT field. You issue EOV if SMitching of magnetic tape or 
direct access volumes is necessary, or if secondary allocation 
i s to be performed for a direct access data set opened for 
output. 

For magnetic tape, you must issue EOV Mhen either a tapemark is 
read or a reflective spot is written over. In these cases, bit 
settings in the 1-byte DCBOFLGS field of the data control block 
determine the action to be taken Mhen EOV is executed. Before 
issuing EOV for magnetic tape, you must make sure that 
appropriate bits are set in DCBOFLGS. Bit positions 2, 3, 6, 
and 7 of DCBOFLGS are used only by the system; you are concerned 
Mith bit positions 0, 1, 4, and 5. The use of these DCBOFLGS 
bit positions is as folloMS^ 

Bit 

set to 1 indicates that a Mrite command Mas executed and 
that a tapemark is to be Mritten. 

Bit 1 

indicates that a backMard read Mas the last I/O operation. 
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Bit 4 



indicates that data sets of unlike attributes area to be 
concatenated. 



Bit 5 

indicates that a tapemark has been read. 

If bits and 5 of DCBOFLGS are both off uihen EOV is executed* 
the tape is spaced past a tapemark* and standard labels* if 
present* are verified on both the old and neM volumes. The 
direction of spacing depends on bit 1. If bit 1 is off* the 
tape i s spaced forioiard* if bit 1 is on* the tape is backspaced. 

If bit is on* but bit 5 is off* Mhen EOV is executed* a 
tapemark is written immediately folloujing the last data record 
of the data set. Standard labels* if specified* &risi created on 
the old and the neM volume. 



After issuing EOV for sequ 
direct access volumes* you 
space Mas obtained on the 
this by examining the data 
control block (UCB). If n 
shoMn in the DEB* nor the 
UCB* have changed* additio 
volume. OtherMise* space 



entially organized output data sets on 

can determine whether additional 
same or a different volume. You do 

extent block (DEB) and the unit 
either the address of the UCB* as 
volume serial number* as shown in the 
nal space Mas obtained on the same 
Mas obtained on a different volume. 



The only parameter of the EOV macro instruction is! 



[symbol! 


EOV 


deb address 



deb address — A-tvpe address* (2-12)* or (1) 

the address of the data control block that is opened for 
the data set. If this parameter is specified as (1)* 
register 1 must contain this address. 

Note: To learn hoM the system disposes of a tape volume Mhen an 
EOV macro is issued* see the description of the DISP parameter 
under "OPEN — Initialize Data Control Block" on page 87. 






CLOSE — RESTORE DATA CONTROL BLOCK 



The CLOSE macro instruction restores one or more data control 
blocks so that processing of their associated data sets can be 
terminated. You must issue CLOSE for all data control blocks 
that Mere used by your channel programs. Some of the procedures 
performed Mhen CLOSE is executed are' 

• Release of data extent block (DEB) 

• Removal of information transferred to data control block 
fields Mhen OPEN Mas executed 

• Verification or creation of standard labels 

• Volume disposition 

• Release of programmer-written appendage routines 

Mhen CLOSE is issued for data sets on magnetic tape volumes* 
labels are processed according to bit settings in the DCBOFLGS 
field of the data control block. Before issuing CLOSE for 
magnetic tape* you must set the appropriate bits in DCBOFLGS. 
The DCBOFLGS bit positions that you are concerned Mith are 
listed in the EOV macro instruction description. 

For information about the forms of the CLOSE macro and their 
parameters* refer to Data Management Macro Instructions . 
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CONTROL BLOCK FIELDS 






The fields of the input/output blocks event control block* and 
data extent block are illustrated and explained here; the data 
control block fields are described with the parameters of the 
DCB macro instruction under "EXCP Requirements" on page 68. 



INPUT/OUTPUT BLOCK FIELDS 



o 



The input/output block (lOB) is not automatically constructed by 
a macro instruction; it must be defined as a series of constants 
and must be on a fullword boundary. For unit-record and tape 
devices* the lOB is 32 bytes in length. For direct access* 
teleprocessing* and graphic devices* 8 additional bytes must be 
provided. You may want to use the system mapping macro lEZIOB* 
Mhich expands into a DSECT* to help in constructing an lOB. 

In Figure 22 the diagonally-ruled areas indicate fields in which 
you must specify information. The other fields are used by the 
system and must be defined as all zeros. You may not place 
information into these fields* but you may examine them. 

lOBFLAGl (1 byte) 

You must set bit positions 0* 1* and 6. One-bits in 
positions and 1 indicate data chaining and command 
chaining* respectively. (If both data chaining and command 
chaining are specified* the system does not use error 
recovery routines except for the 2671* 1052* 2150* and the 
direct access devices.) A one-bit in position 6 indicates 
that the channel program is not a 'related' request* that 
is, the channel program is not related to any other channel 
program. If you intend to issue an EXCP macro with a BSAM* 
QSAM* or BPAM^ data control block* you may want to turn on 
bit 7 to prevent access-method appendages from processing 
the I/O request. 

I0BFLAG2 (1 byte) 

If you set bit 6 in the lOBFLAGl field to zero* then bits 2 
and 3 in this field must be set to- 

• 00, if any channel program or appendage associated with 
a related request might modify this lOB or channel 
program. 

• 01, if the conditions requiring a 00 setting don't 
apply, but the CHE or ABE appendage might retry this 
channel program if it completes normally or with the 
unit-exception or wrong-length-record bits on in the 
CSW. 

• 10 in all other cases. 

The three combinations of bits 2 and 3 represent the three 
kinds of related requests* known as type 1 (00)* type 2 
(01)* and type 3 (10). The type you use determines how 
much the EXCP Processor can overlap the processing of 
related requests. Type 3 allows the greatest overlap* 
normally making it possible to quickly reuse a device after 
a channel-end interruption. (Related requests that were 
executed on a pre-MVS system are executed as type-1 
requests if not modified.) 

lOBSENSO and lOBSENSl (2 bytes) 

are placed into the input/output block by the EXCP 
Processor when a unit check occurs. On occasion* the 
system is unable to obtain any sense bytes because of unit 
checks when sense commands are issued. In this case the 
system simulates sense bytes by moving X'lOFE' to lOBSENSO 
and lOBSENSl. 

lOBECBCC (1 byte) 

the first byte of the completion code for the channel 
program. The system places this code in the high-order 
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0(0)/ 
////// 
////// 



lOBFLAGl 



4(4) 



lOBECBCC 



8(8) 



I0BFLAG3 



I0BFLAG2 



lOBSENSO 



lOBSENSl 



////////////////////////////////////// 
/////////////// lOBECBPT ///////////// 
////////////////////////////////////// 



12(C) 



lOBCSU 



16(10) 



lOBSIOCC 



20(14) 



Reserved 



24(18) 



lOBRESTR 



////////////////////////////////////// 
/////////////// lOBSTART ///////////// 
////////////////////////////////////// 



////////////////////////////////////// 
/////////////// lOBDCBPT ///////////// 
////////////////////////////////////// 



IOBRESTR+1 



28 (IC) ///////////////////////// 
//////////// lOBINCAM ////////// 
//////////////////////////////// 



32(20) ////////// 
/// lOBSEEK // 
/ (first byte, M) 



lOBERRCT 



> All 
Devices 



> Direct Access, Teleprocessing, and 
■^ Graphic Devices 



33(21 ) /////////////////////////////// 
////////////////////////////////////// 
////////////////////////////////////// 
/// lOBSEEK //// 

/////////////////////// (second through eighth bytes, //// 
/////////////////////// BBCCHHR) //// 

/////////////////////////////////////////////////// 39(27) 



Direct 

Access 

> Storage 

Devices 

(DASD) 



Figure 22. Input/Output Block Format 



byte of the event control block when the channel program is 
posted complete. The completion codes and their meanings 
are listed under "Event Control Block Fields** on page 97. 

lOBECBPT (3 bytes) 

the address of the 4-byte event control block you have 
provided. 

I0BFLAG3 (1 byte) 

is used only by the system. 

lOBCSW (7 bytes) 

the loM-order seven bytes of the channel status word, Mhich 
are placed into this field each time a channel-end or PCI 
interruption occurs. 

lOBSIOCC (1 byte) 

in bits and 1, the instruction-length code; in bits 2 and 
3, the start I/O (SIO) condition code for the instruction 
the system issues to start the channel program; and in bits 
4 through 7> the program mask. 
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lOBSTART (3 bytes) 
-<i^ the starting address of the channel program to be executed. 

Reserved (1 byte) 

used only by the system. 

lOBDCBPT (3 bytes) 

the address of the data control block of the data set to be 
read or written by the channel program. 

lOBRESTR (1 byte) 

used by the system for volume repositioning in error 
recovery procedures. 

IOBRESTR+1 (3 bytes) 

used by the system* if a related channel program is 
permanently in error* to chain together lOBs that represent 
dependent channel programs. To learn more about the 
conditions under which the chain is built* refer to 
"Interruption Handling and Error Recovery Procedures" on 
page 71. 

lOBINCAM (2 bytes) 

for magnetic tape* the amount by which the block count 
(DCBBLKCT) field in the device-dependent portion of the 
data control block is to be incremented. You may alter 
these bytes at any time. For forward operations* these 
bytes should contain a binary positive integer (usually 
-t-l); for backward operations* they should contain a binary 
negative integer. Uhen these bytes are not used* all zeros 
must be specified. 

Reserved (2 bytes) 

used only by the system. 

lOBSEEK (first byte* M) 

for direct access devices* the extent entry in the data 
extent block that is associated with the channel program (0 
indicates the first entry* 1 indicates the second* and so 
forth). For teleprocessing and graphic devices* it 
contains the UCB index. 

lOBSEEK (last 7 bytes* BBCCHHR) 

for direct access devices* the seek address for your 
channel program. 

EVENT CONTROL BLOCK FIELDS 

You must define an event control block (ECB) as a 4-byte area on 
a fullword boundary. Mhen the channel program has been 
completed* the input/output supervisor places a completion code 
containing status information into the ECB (Figure 23 on page 
98), Before examining this information* you must test for the 
setting of the "complete bit." If the complete bit is not on, 
and your problem program cannot perform other useful operations* 
you should issue a MAIT macro instruction that specifies the 
event control block. Under no circumstances should you 
construct a program loop that tests for the complete bit. 

DATA EXTENT BLOCK FIELDS 

The data extent block (DEB) is constructed by the system when an 
OPEN macro instruction is issued for the data control block. 
You may not modify the fields of the DEB* but you may examine 
them. The DEB format and field descriptions are contained in 
Debugging Handbook . 



o 
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WAIT bit=0 


COMPLETE bit=l 


Remainder of completion code 



bit 




31 



Mait bit 

A one— bit in this position indicates that the UAIT macro instruction has been 
issued^ but the channel program has not been completed. 

Complete bit 

A one— bit in this position indicates that the channel program has been 
completed; if it has not been completed* a zero— bit is in this position. 

Completion code 

This code* Mhich includes the Mait and complete bits* may be one of the 
folloMing 4— byte hexadecimal expressions: 

Code Heaning 

7F000OOO The channel program has terminated without error. 

41000000 The channel program has terminated with a permanent error. 

42000000 The channel program has terminated because a direct access extent 
address has been violated. 

44000000 The channel program has been intercepted because of a permanent error 
associated Mith a device end for the previous request. You may 
reissue the EXCP macro instruction to restart the channel program. 

48000000 The reauest queue element for a channel program has been made 
available after it has been purged. 

4B000000 One of the folloMing errors occurred during error recovery processing 
for a tape device. 

• The CSU command address in the lOB is zeros. 

• An unexpected load point Mas encountered. 






Error recovery routines have been entered because of direct access 
error but are unable to read the home address or record 0. 



4F000000 
Figure 23. Event Control Block after Posting of Completion Code (EXCP) 



EXECUTING FIXED CHANNEL PROGRAMS IN REAL STORAGE (EXCPVR) 



The EXCPVR macro instruction provides you Mith the same 
functions as the EXCP macro instruction (that is» a 
device-dependent means of performing input/output operations). 
In addition* it alloHs your program to improve the efficiency of 
the I/O operations in a paging environment by translating its 
OMn virtual channel programs to real channel programs. 
Authorized programs are allowed to execute in a V=V area and 
provide the EXCP processor Mith real channel programs. This 
eliminates the translation of channel programs by the EXCP 
processor. The program issuing the EXCPVR must remain in 
authorized state until the completion of the channel programs. 

Problem programs are authorized to use the EXCPVR macro 
instruction under the authorized program facility (APF). A 
description of hoM to authorize a program can be found in System 
Programming Library^ Supervisor Services and Macro Instructions . 



\y 
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[symbol] 


EXCPVR 


iob-address 



#>,, 



iob-address — A-tvpe addre5s> (2-12) t or (1) 

the address of the input/output block of the channel 
program to be executed. 

To use EXCPVR» you must do all the things you Mould do to 
execute an EXCP request; in addition you must* 

1. Code PGFX=YES in the DCB associated Mith the EXCPVR requests 
and provide a page-fix (PGFX) appendage by specifying 
SIOA=symbol in the DCB. 

2. Fix the data area that contains your channel program^ the 
data areas that are referred to by your channel program^ 
your PCI appendage (if your program can generate program 
controlled interrupts)* and any area referred to by your PCI 
appendage. To cause EXCP to fix these data areas* you build 
a list that contains the addresses of these virtual areas. 
You should build the list in your PGFX appendage. 

3. Determine uihether the data areas in virtual storage 
specified in the address fields of your CCMs cross page 
boundaries. If they do> you must build an indirect data 
address list (IDAL) and put the address of the IDAL in the 
affected CCW. 

4. Translate the addresses in your CCUs from virtual to real 
addresses. 

Items 3 and 4 must be done in your start-I/0 (SIO) appendage. A 
description of the SIO appendage is presented under "Appendages" 
on page 72. 



BUILDING THE LIST OF DATA AREAS TO BE FIXED 



The EXCP processor expects programs using the EXCPVR macro 
instruction to pass a list of data areas to be fixed. This list 
is to be built in the PGFX appendage* as described beloM. 

The data areas you must fix in real storage (if not already 
fixed in real storage) are^ 

1. The channel program. If the channel program is already in a 
fixed subpool* it does not have to be fixed. 

2. The data areas from which your channel program will be 
writing and to which your channel program will be reading. 
If the data areas are already in a fixed subpool* they do 
not have to be fixed. 

3. The PCI appendage* if used* and any areas referred to in the 
PCI appendage. 

4. Any system or user control blocks (as well as* the DEB). 

You need not fix areas that have already been fixed* such as the 
modules that reside in the fixed link pack area (LPA). 



PAGE FIX (PGFX) AND START-I/0 (SIO) APPENDAGE 



O 



This appendage comprises two essentially independent appendages. 
The complete appendage can be viewed as a reenterable subroutine 
having two entry points* one for the SIO appendage and one for 
the PGFX appendage. 

The SIO entry point is located at offset in the subroutine* 
any other location in the appendage may be branched to from this 
entry point. The entry point of the PGFX appendage is at offset 
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-i-4 in the SIO subroutine* uhich is set in register 15 as the 
entry point of the PGFX appendage. 

Page Fix (PGFX) Appendage: The purpose of this appendage is to 
list all of the areas that must be fixed to prevent paging 
exceptions during the execution of the current I/O request. 
This appendage may be entered more than once. Houiever* each 
time it is entered* it must create the same list of areas to be 
fixed. The appendage may use the 16~Mord save area pointed to 
by register 13. Registers 10> 11* and 13 may be used as Mork 
regi sters. 



Page-Fix List Processing 



Each page-fix entry placed in the list by the appendage must 
have the following doubleNord format: 



X'OO' 



< — 1 byte — > 



Starting virtual 
address of area 
to be fixed 



■3 bytes- 



X'OO' 



< — 1 byte — > 



Ending virtual 
address of 
area to be fixed 
y 1 



'3 bytes- 



On return from your PGFX appendage to the EXCP processor (via 
the return address provided in register 14), register 10 must 
point to the first page-fix entry and register 11 must contain 
the number of page-fix entries in the Mork area. The EXCP 
processor then fixes the pages corresponding to the areas listed 
by the PGFX appendage. The pages remain fixed until the 
associated I/O request terminates. 

If either the channel end appendage or the abnormal end 
appendage returns via the return address in register 14 plus 8> 
the PGFX appendage is not normally reentered. Instead* the SIO 
appendage is entered* and the page-fix list built by the PGFX 
appendage is still active. However* the PGFX appendage is 
entered after either the channel end appendage or the abnormal 
end appendage returns via the return address in register 14 plus 
8 uihen a PURGE macro has been issued (for instance* when a 
memory suiap has occurred). In this case* when I/O is restored* 
the PGFX appendage is entered. 

Note: The page-fix list must be in page-fixed storage. 

SIO APPENDAGE: If you are using EXCPVR to execute your channel 
program* you must translate the virtual addresses in the 
operands of your channel program to real addresses. This should 
be done in your SIO appendage. If indirect data addressing is 
required* the SIO appendage should also build the indirect data 
address lists (IDALs) and turn on the IDA indicators in the 
associated CCUs. 

Translating Virtual Addresses and Building the ZDAL: You must 
convert the virtual addresses in the channel program to real 
addresses. You must also check the areas whose addresses appear 
in bits 8-31 of your CCMs to determine whether the data areas 
cross 2K-byte boundaries. If they do, you must provide an entry 
in the IDAL for each 2K-byte boundary crossed. The channel 
subsystem uses the IDAL to identify the address at which it will 
continue reading or writing when a 2K-byte boundary is crossed 
during a read or write operation. The IDAL must contain real 
addresses when it is processed by the channel. 



Xj^' 
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ecu 



Command 
Code 



Address of the 
IDAL 



04 



////////// 
////////// 



Byte 
Count 



7 8 



31 32 



39 40 
IDAL 



47 48 



First Indirect Data 
Address klord 



Second Indirect Data 
Address Mord 



Subsequent Indirect 
Data Address Uord 






Notes: 

1. You must put one entry in the IDAL for each 2K-byte page 
boundary your data area crosses. 

2. If the ecu has an IDAL address rather than a data address* 
bit 37 must be set to signal this to the channel. 

3. The maximum number of entries needed in the IDAL is 
determined from the count in the CCU as folloMS^ 

Number of IDAL entries=C(CCU byte-count - l)/2048) + 1. 
(Round up division to next highest integer if remainder is 
not zero.) 

The number of IDAL entries required ultimately depends on the 
number of 2K-byte boundaries crossed by the data. For example* 
if your data is 800 bytes long and does not cross a 2K-byte page 
boundary* no IDAL entries are required. If your data crosses a 
4K-byte page boundary* then two IDAL entries are required. If 
your data is 5000 bytes long* at least two IDAL entries are 
required. If your data crosses two 4K-byte page boundaries* 
four IDAL entries are required. 

The first indirect address is the real address of the first byte 
of the data area. The second and subsequent indirect addresses 
are the real addresses of the second and subsequent 2K-byte 
boundaries of the data area. 

For example* if the data area real address is X*707FF* and the 
byte count is X'1802** the IDAL would contain the following real 
addresses (assuming the real addresses are contiguous* which may 
not always be the case): 

707FF 
70800 
71000 

If the data area real address is X'707FF» and the byte count is 
X*800** the IDAL would contain the following addresses: 

707FF 
70800 
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CHAPTER 4. USING XDAP TO READ AND WRITE TO DIRECT-ACCESS DEVICES 



The execute direct access program (XDAP) macro instruction 
provides you with a means of reading, verifying, or updating 
blocks on direct access volumes without using an access method 
and without writing your own channel program. This chapter 
explains what the XDAP macro instruction does and how you can 
use it. The control block generated when XDAP is issued and the 
macro instructions used with XDAP are also discussed. 

Since most of the specifications for XDAP are similar to those 
for the execute channel program (EXCP) macro instruction, you 
should be familiar with the "Executing Your Own Channel Programs 
(EXCP)" chapter of this publication, as well as with the 
information contained in Data Management Services which provides 
how-to information for using the access method routines of the 
system control program. 

INTRODUCTION 



Execute direct access program (XDAP) is a macro instruction that 
you may use to read, verify, or update a block on a direct 
access volume. If you are not using the standard IBM data 
access methods, you can, by issuing XDAP, generate the control 
information and channel program necessary for reading or 
updating the records of a data set. (XDAP cannot be used, 
however, to read, verify, or update a SYSIN or SYSOUT data set.) 

You cannot use XDAP to add blocks to a data set, but you can use 
it to change the keys of existing blocks. Any block 
configuration and any data set organization can be read or 
updated. 

Although the use of XDAP requires less storage than do the 
standard access methods, it does not provide many of the control 
program services that are included in the access methods. For 
example, when XDAP is issued, the system does not block or 
deblock records and does not verify block length. 

To issue XDAP, you must provide the actual track address of the 
track containing the block to be processed. You must also 
provide either the block identification or the key of the block, 
and specify which of these is to be used to locate the block. 
If a block is located by identification, both the key and data 
portions of the block may be read or updated. If a block is 
located by key, only the data portion can be processed. 

For additional control over I/O operations, you may write 
appendages, which must be entered into the LPA library. 
Descriptions of these routines and their coding specifications 
are included under "Executing Your Own Channel Programs (EXCP)." 






XDAP REQUIREMENTS 



Uhen using the XDAP macro instruction, you must, somewhere in 
your program, code a DCB macro instruction, which produces a 
data control block (DCB) for the data set to be read or updated. 
You must also code an OPEN macro instruction, which initializes 
the data control block and produces a data extent block (DEB). 
The OPEN macro instruction must be executed before any XDAP 
macro instructions are executed. 
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Mhen the XDAP macro instruction is assembled^ a control block 
and executable code are generated. This control block may be 
logically divided into three sections^ 

• An event control block (ECB)> Mhich is supplied kiith a 
completion code each time the direct access channel program 
is terminated. 

• An input/output block, (IOB)» which contains information 
about the direct access channel program. 

• A direct access channel program, which consists of three or 
four channel command words (CCUs). The type of channel 
program generated depends on specifications in the 
parameters of the XDAP macro instruction, klhen executed, it 
locates a block by either its actual address or its key and 
reads, updates, or verifies the block. 

Uhen the channel program has terminated, a completion code is 
placed into the event control block. After issuing XDAP, you 
should therefore issue a WAIT macro instruction, specifying the 
address of the event control block, to regain control when the 
direct access program has terminated. If volume switching is 
necessary, you must issue an EOV macro instruction. Uhen 
processing of the data set has been completed, you must issue a 
CLOSE macro instruction to restore the data control block. 



HACRO SPECIFICATIONS FOR USE WITH XDAP 



o 



Uhen you are using the XDAP macro instruction, you must also 
code DCB, OPEN, CLOSE, UAIT, and, in some cases, the EOV macro 
instructions. The parameters of the XDAP macro instruction are 
listed and described here. For the other required macro 
instructions, special requirements or options are explained, but 
you should refer to "Macro Specifications for Use with EXCP" on 
page 80 for listings of their parameters. 



DCB — DEFINE DATA CONTROL BLOCK 



You must issue a DCB macro instruction for each data set to be 
read, updated, or verified by the direct access channel program. 
Refer to "DCB — Define Data Control Block for EXCP" on page 80 to 
learn which macro instruction parameters to code. 



OPEN — INITIALIZE DATA CONTROL BLOCK 



O 



The OPEN macro instruction initializes one or more data control 
blocks so that their associated data sets can be processed. You 
must issue OPEN for all data control blocks that are to be used 
by the direct access program. Some of the procedures performed 
when OPEN is executed are: 

• Construction of data extent block (DEB). 

• Transfer of information from DD statements and data set 
labels to the data control block. 

• Verification or creation of standard labels. 

• Loading of programmer-written appendage routines. 

The two parameters of the OPEN macro instruction are the 
address(es) of the data control block(s) to be initialized, and 
the intended method of I/O processing of the data set. The 
method of processing may be specified as INPUT, OUTPUT, EXTEND; 
however, if nothing is specified, INPUT is assumed. 
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XDAP-~EXECUTE DIRECT-ACCESS PROGRAM 



The XDAP macro instruction produces the XDAP control block (that 
\5f the ECB» JOB/ and channel program) and executes the direct 
access channel program. The format of the XDAP macro 
instruction is? 



[symbol] 


XDAP 


ecb-symbol 

»type 

»dcb-addr 

»area-addr 

•length-value 

• [ ( kev-addr > kevlenath-value ) 3 

»blkref-addr 

» [sectoi — addr] 

C,MF=CE|U1 



ecb-svmbol- — symbol or (2-12) 

the symbolic name to be assigned to the XDAP event control 
block. Registers can be used only with MF^E. 

tyjaezrCRI I RK I WI I HK I VI I VK} 

the type of I/O operation intended for the data set and the 
method by which blocks of the data set are to be located. 
One of the combinations shoMn must be coded in this field. 

The codes and their meanings &rG' 

R Read a block. 

U Update a block. 

V Verify that the device is able to read the contents of 
a blocks but do not transfer data. 

I Locate a block by identification. (The key portion* if 
present » and the data portion of the block srG read, 
updated* or verified.) 

K Locate a block by key. (Only the data portion of the 

block is read* updated* or verified.) If you code this 
value* you must code the *key-addr*keylength-value' 
operands. 

dcb-addr — A-tvpe address or (2-12) 

the address of the data control block for the data set. If 
this data control block is also being used by a sequential 
access method (BSAM* BPAM* QSAM)* you must reassemble the 
XDAP macro instruction. OtherMise* sequential access 
method appendages Mill be called at the conclusion of the 
XDAP channel program. 

area-addr — A-tvpe address or (2-12) 

the address of an input or output area for a block of the 
data set. 



length-value — -absexp or (2-12) 

the number of bytes to be transferred to or from the input 
or output area. If blocks are to be located by 
identification and the data set contains keys* the value 
must include the length of the key. The maximum number of 
bytes transferred is 32*767. 

key-addi RX-tvpe address or (2-12) 

when blocks are to be located by key* the address of a 
virtual storage field that contains the key of the block to 
be read* updated* or verified. 

kevlength-value — absexp or (2-12) 

when blocks are to be located by key* the length of the 
key. The maximum length is 255 bytes. 



c 



104 MVS/370 System Programming Library: Data Management 






blkref-addr — |gX-tvpe address or (2-12) 

the address of a field in virtual storage containing the 
actual track address of the track containing the block to 
be located. The actual address of a block is in the form 
NBBCCHHR» Mhere K indicates Mhich extent entry in the data 
extent block is associated with the direct access program; 
BB is not used but must be zero; CC indicates the cylinder 
address; HH indicates the actual track address; and R 
indicates the block identification. R is not used Mhen 
blocks are to be located by key. (For more detailed 
information* see "Conversion of Relative Track Address to 
Actual Track Address" on page 107.) 

sector-addr— RX-tvpe address or (2-12) 

the address of a 1-byte field containing a sector value. 
The sector-address parameter is used for rotational 
position sensing (RPS) devices only. The parameter is 
optional* but its use uill improve channel performance. 
Uhen the parameter is coded* a set-sector CCkl (using the 
sector value indicated by the data address field) precedes 
the search-ID-equal command in the channel program. The 
sector-address parameter is ignored if the type parameter 
is coded as RK* UK* or VK. If a sector address is 
specified in the execute form of the macro* then a sector 
address* not necessarily the same* must be specified in the 
list form. The sector address in the executable form Mill 
be used. 

Note: No validity check is made on either the address or 
the sector value Mhen the XDAP macro is issued. HoMever* a 
unit check/command reject interruption Mill occur during 
channel-program execution if the sector value is invalid 
for the device or if the sector-addr operand is used Mhen 
accessing a device Mithout RPS. (For more detailed 
information* see "Obtaining Sector Number of a Block on a 
Device Hith the RPS Feature" on page 109.) 

HF= 

you may use the L-form of the XDAP macro instruction for a 
macro expansion consisting of only a parameter list* or the 
E-form for a macro expansion consisting of only executable 
instructions. 

The first operand (ecb-symbol) is required and may be coded 
as a symbol or supplied in registers 2 through 12. The 
type* dcb-addr* area-addr* and length-value operands may be 
supplied in either the L- or E-form. The blkref-addr 
operand may be supplied in the E-form or moved into the 
lOBSEEK field of the lOB by you. The sector-addr is 
optional; it may be coded either in both the L- and E-form 
or in neither. 

The first tHO operands (ecb-symbol and type) are required 
and must be coded as symbols. If you choose to code 
length-value or keylength-value* they must be absolute 
expressions. Other operands* if coded* must be A-type 
addresses, (blkref-addr is ignored if coded.) 

The dcb-addr* area-addr* blkref-addr* and sector-value operands 
may be coded as RX-type addresses or supplied in registers 2 
through 12. The length-value and keylength-value operands can 
be specified as absolute expressions or decimal integers or 
supplied in registers 2 through 12. 



riF=E 



MF=U 
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EOV — END OF VOLUME 



The EOV macro instruction identifies end-of-volume and 
end-of-data-set conditions. For an en d-of- volume condition* EOV 
causes switching of volumes and verification or creation of 
standard labels. For &n end~of-data-set condition* EOV causes 
your end-of-data-set routine to be entered. Uhen using XDAP* 
you issue EOV if switching of direct access volumes is 
necessary* or if secondary allocation is to be performed for a 
direct access data set opened for output. 

The only parameter of the EOV macro instruction is the address 
of the data control block of the data set. 



CLOSE — RESTORE DATA CONTROL BLOCK 



The CLOSE macro instruction restores one or more data control 
blocks so that processing of their associated data sets can be 
terminated. You must issue CLOSE for all data sets that were 
used by the direct access channel program. Some of the 
procedures performed when CLOSE is executed are: 

• Release of data extent block (DEB) 

• Removal of information transferred to data control block 
fields Mhen OPEN Mas executed 

• Verification or creation of standard labels 

• Release of programmei — written appendage routines 

The CLOSE macro instruction must identify the address of at 
least one data control block to be restored* and may specify 
other options. See Data Management Macro Instructions to learn 
what these options are and how they are specified. 



CONTROL BLOCKS USED WITH XDAP 



EVENT CONTROL BLOCK 



XNPUT/OUTPUT BLOCK 



The three control blocks generated during execution of the XDAP 
macro instruction are described here. 



The event control block (ECB) begins on a fullword boundary and 
occupies the first 4 bytes of the XDAP control block. Each time 
the direct access channel program terminates* the I/O supervisor 
places a completion code containing status information into the 
event control block (Figure 24 on page 107). Before examining 
this information* you must wait for the completion of the 
channel program by issuing a MAIT macro instruction that 
specifies the address of the event control block. 



The input/output block (lOB) is 40 bytes in length and 
immediately follows the event control block. "Control Block 
Fields" on page 95 contains a diagram of the input/output block 
(Figure 24 on page 107). You may want to examine the lOBSENSO* 
lOBSENSl* and lOBCSW fields if the ECB is posted with X»41'. 
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WAIT bit 


COMPLETE bit 


Completion code 



bit 




31 



Uait bit 

A one bit in this position indicates that the direct access channel program has 
not been completed. 

Complete bit 

A one bit in this position indicates that the channel program has been 
completed; if it has not been completed^ a zero bit is in this position. 

Completion code 

This code^ ujhich includes the Mait and complete bits, may be one of the 
following 4— byte hexadecimal expressions^ 

Code Meaning 

7F000000 Direct access program has tcrininattid Mithoul errof. 

41000000 Direct access program has terminated with permanent error. 

42000000 Direct access program has terminated because a direct access extent 
address has been violated. 



Error recovery routines have been entered because of direct access 
error but are unable to read home address or record 0. 



4F000000 
Figure 24. Event Control Block after Posting of Completion Code (XDAP) 






DIRECT ACCESS CHANNEL PROGRAM 

The direct access channel program is 24 bytes in length (except 
when set sector is used for RPS devices) and immediately follows 
the input/output block. Depending on the type of I/O operation 
specified in the XDAP macro instruction, one of four channel 
programs may be generated. The three channel command words for 
each of the four possible channel programs are shown in 
Figure 25 on page 108. 

Uhen a sector address is specified with an RI» VI » or MI 
operation, the channel program i s 32 bytes in length. Each of 
these channel programs in Figure 25 would be, in this case, 
preceded by a set sector command. 

CONVERSION OF RELATIVE TRACK ADDRESS TO ACTUAL TRACK ADDRESS 

To issue XDAP, you must provide the actual track address of the 
track containing the block to be processed. If you know only 
the relative track address, you can convert it to the actual 
address by using a resident system routine. The entry point to 
this conversion routine is labeled lECPCNVT. The address of the 
entry point (CVTPCNVT) is in the communication vector table 
(CVT). The address of the CVT is in location 16. (For the 
displacements and descriptions of the CVT fields, see Debugging 
Handbook. ) 



o 
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Type of I/O operation ecu command code 

Read by identification 1 Search ID Equal 

2 Transfer in Channel 

Verify by identification* 3 Read Key and Data 

Read by key 1 Search Key Equal 

2 Transfer in Channel 

Verify by key* 3 Read Data 

Urite by identification 1 Search ID Equal 

2 Transfer in Channel 

3 Urite Key and Data 

Urite by key 1 Search Key Equal 

2 Transfer in Channel 

3 Urite Data 

* For verifying operations^ the third CCU is flagged to 
suppress the transfer of information to virtual storage. 

Figure 25, The XDAP Channel Programs 



The conversion routine does all its Mork in general registers. 
You must load registers 0» 1» 2» 14» and 15 Mith input to the 
routine. Register usage i s as folloMs: 



Register Use 

Must be loaded Mith a 4-byte value of the form TTRN> 
Mhere TT is the number of the track relative to the 
beginning of the data set» R is the identification of 
the block on that tracks and N is the concatenation 
number of a BPAM data set. (0 indicates the first 
data set in the concatenation* an unconcatenated BPAM 
data set» or a non-BPAM data set.) 

1 Must be loaded Mith the address of the data extent 
block (DEB) of the data set. 

2 Must be loaded Mith the address of an 8-byte area that 
is to receive the actual address of the block to be 
processed. The converted address is of the form 
MBBCCHHR» Mhere M indicates Mhich extent entry in the 
data extent block is associated Mith the direct access 
program (0 indicates the first extent » 1 indicates the 
second* and so forth); BB is tMo bytes of zeros; CC is 
the cylinder address; HH is the actual track address; 
and R is the block number. 

3-8 Are not used by the conversion routine. 

9-13 Are used by the conversion routine and are not 
restored. 

14 Must be loaded Mith the address to Mhich control is to 
be returned after execution of the conversion routine. 

15 Is used by the conversion routine as a base register 
and must be loaded Mith the address at Mhich the 
conversion routine is to receive control. 



^^(tarf^ 
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Uhen control is returned to your program* register 15 Mill 
contain one of the following return codes! 

Code Meaning 

0(00) Successful conversion. 

4(04) The relative block address converts to an actual track 
address outside the extents defined in the DEB. 






CONVERSION OF ACTUAL TRACK ADDRESS TO RELATIVE TRACK ADDRESS 

To get the relative track address uihen you knoM the actual track 
address* you can use the conversion routine labeled lECPRLTV. 
The address of the entry point (CVTPRLTV) is in the 
communication vector table (CVT). The address of the CVT is in 
location 16. 

The conversion routine does all of its uiork in general 
registers. You must load registers 1» 2» 14> and 15 Mith input 
to the routine. Register usage is as follows: 

Register use 

Mill be loaded Mith the resulting TTRO to be passed 
back to the caller. 

1 Must be loaded Mith the address of the data extent 
block (DEB) of the data set. 

2 Must be loaded Mith the address of an 8-byte area 
containing the actual address to be converted to a 
TTR. The actual address is of the form MBBCCHHR. 

3-8 Are not used by the conversion routine. 

9-13 Are used by the conversion routine and are not 
restored. 

14 Must be loaded Mith the address to Mhich control is to 
be returned after execution of the conversion routine. 

15 Is used by the conversion routine as a base register 
and must be loaded with the address at Mhich the 
conversion routine is to receive control. 



OBTAINING SECTOR NUMBER OF A BLOCK ON A DEVICE NITH THE RPS FEATURE 

To obtain the performance improvement given by rotational 
position sensing* you should specify the sector-addr parameter 
in the XDAP macro. For programs that can be used Mith both RPS 
and non-RPS devices* the UCBRPS bit (bit 3 at an offset of 17 
bytes into the UCB) should be tested to determine Mhether the 
device has rotational position sensing. If the UCBRPS bit is 
off* a channel program Mith a "set sector" command must not be 
issued to the device. 

The sector-addr parameter on the XDAP macro specifies the 
address of a one-byte field in your region. You must store the 
sector number of the block to be located in this field. You can 
obtain the sector number of the block by using a resident 
conversion routine* lECOSCRl. The address of this routine is in 
field CVTOSCRl of the CVT, and the address of the CVT is in 
location 16. The routine should be invoked via a BALR 14*15 
instruction. If you are passing the track balance to the 
routine* you invoke the routine using a BAL 14*8(15). 
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For RPS devices* the conversion routine does all its Mork in 
general registers. You must load registers 0» 2, 14* and 15 
Mith input to the routine. Register usage is as follows! 

Register use 

For fixed* standard blocks or fixed* unblocked 
records not in a partitioned data set: Register 
must be loaded uiith a 4-byte value in the form XXKR* 
Mhere XX is a 2-byte field containing the physical 
block size* K is a 1-byte field containing the key 
length* and R is a l-byte field containing the number 
of the record for vjhich a sector value is desired. 
The high-order bit of register must be turned off 
(set to 0) to indicate fixed-length records. 

Passing the track balance^ Register must be loaded 
with the 4-byte value of the track balance of the 
record preceding the required record. 

For all other cases: Register must be loaded with a 
4-byte value in the form BBIR* where BB is the total 
number of key and data bytes on the track up to* but 
not including* the target record; I is a 1-byte key 
indicator (1 for keyed records* for records without 
keys); and R is a 1-byte field containing the number 
of the record for which a sector value is desired. 
The high-order bit of register must be turned on 
(set to 1) to indicate variable-length records. 

1 Not used by the sector-convert routine. 

2 Must be loaded with a 4-byte field in which the first 
byte is the UCB device type code for the device 
(obtainable from UCB-i-19)* and the remaining three 
bytes ar& the address of a 1-byte area that is to 
receive the sector value. 

3-8*12*13 Not used. 

9-11 Used by the convert routine and are not saved or 
restored. 

14 Must be loaded with the address to which control is 
to be returned after execution of the sector 
conversion routine. 

15 Used by the conversion routine as a base register and 
must be loaded with the address of the entry point to 
the conversion routine. 
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CHAPTER 5. PASSWORD PROTECTING YOUR DATA SETS 






INTRODUCTION 



OS/VS password protection does not apply to VSAM data sets. 
Information about VSAM data set protection is in VSAM Reference 
and Access Method Services Reference . For information on RACF 
and its relationship to password protection* refer to Resource 
Access Control Facility (RACF)' General Information Manual . To 
use the data set protection feature of the operating system, you 
must create and maintain a PASSUIORD data set consisting of 
records that associate the names of the protected data sets with 
the password assigned to each data set. There are four ways to 
maintain the PASSUIORD data set: 

• You can write your own routines. 

• You can use the PROTECT macro instruction. 

• You can use the utility control statements of the lEHPROGM 
utility program. 

• If you have TSO, you can use the TSO PROTECT command. 

This chapter discusses only the first two of the four ways: It 
provides technical detail about the PASSUIORD data set that is 
necessary for writing your own routines, and it describes how to 
use the PROTECT macro instruction. (The last two of the four 
ways are discussed in other publications, as indicated in the 
list of publications below.) 

Before using the .information in this chapter, you should be 
familiar with information in several related publications. The 
following publications are recommended: 

• Data Management Services contains a general description of 
the data set protection feature. 

• Message Library: System Messages contains a description of 
the operator messages and replies associated with the data 
set protection feature. 

• JCl contains a description of the data definition (DD) 
statement parameter used to indicate that a data set is to 
be password protected. 

• DADSM and Common VTOC Access Faci li tv Diagnosis Guide and 
DADSM Diagnosis Reference contain a description of the 
PASSWORD data set record format. 

• Uti li ti es contains a description of how to maintain the 
PASSWORD data set using the utility control statements of 
the lEHPROGM utility program. 

• TSO Command Language Reference describes the use of the TSO 
PROTECT command. 



In addition to the usual label protection that prevents opening 
of a data set without the correct data set name, the operating 
system provides data set security options that prevent 
unauthorized access to confidential data. Password protection 
prevents access to data sets, until a correct password is 
entered by the system operator, or, for TSO, by a remote 
terminal operator. 
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The folloMing are the types of access alloNed to 
passMord-protected data sets* 

• PWREAD/PWWRITE — A passMord is required to read or Mrite. 

• PWREAD/NOWRITE — A passuiord is required to read. Writing is 
not alloMed. 

• NOPWREAD/PWWRITE — Reading is allowed without a password. A 
password is required to write. 

To prepare for use of the data set protection feature of the 
operating system^ you place a sequential data set* named 
PASSUORD> on the system residence volume. This data set must 
contain at least one record for each data set placed under 
protection. In turn* each record contains a data set name» a 
password for that data set» a counter field* a protection mode 
indicator* and a field for recording any information you desire 
to log. On the system residence volume* these records are 
formatted as a "key area" (data set name and password) and a 
"data area" (counter field* protection mode indicator* and 
logging field). The data set is searched on the "key area." 

Note: The area allocated to the data set should not have been 
previously used for a PASSUORD data set as this may cause 
unpredictable results when adding records to the data set. 

You can write routines to create and maintain the PASSUIORD data 
set. If you use the PROTECT macro instruction to maintain the 
PASSWORD data set* see "Using the PROTECT Macro Instruction to 
Maintain the PASSWORD Data Set" on page 115. If you use the 
lEHPROGM utility program to maintain the PASSWORD data set* see 
Uti 1 i ties . These routines may be placed in your own library or 
the system's library (SYSl .LINKLIB) . You may use a data 
management access method or EXCP programming to read from and 
write to the PASSWORD data set. 

If a data set is to be placed under protection* it must have a 
protection indicator set in its label (format-1 DSCB or header 1 
tape label). This is done by the operating system when the data 
set is created* by the lEHPROGM utility program* or* by the 
PROTECT macro when creating or adding the control password. The 
protection indicator is set in response to a value in the LABEL= 
operand of the DD statement associated with the data set being 
placed under protection. The publication JCL describes the 
LABEL operand. 

Kote: Data sets on magnetic tape are protected only when 
standard labels are used. 

Password-protected data sets can only be accessed by programs 
that can supply the correct password. When the operating system 
receives a request to open a protected data set* it first checks 
to see if the data set has already been opened for this job 
step. If so* only the access mode will be checked to determine 
whether it is compatible with the protection mode under which it 
was previously opened. If the data set has not been previously 
opened by this job step* or if the access mode is not compatible 
with the protection mode under which it was previously opened* a 
message is issued that asks for the password* the message goes 
to the operator console. If the program requesting that the data 
set be opened is running under TSO in the foreground* the 
message goes to the TSO terminal operator. If you want the 
password supplied by another method in your installation* you 
can modify the READPSWD source module or code a new routine to 
replace READPSWD in SYSl.LPALIB. 



o 



^fclc**^ 



112 MVS/370 System Programming Library: Data Management 






PAS8U0RD DATA SET CHARACTERISTICS 



^r\,. 



The PASSUORD data set must reside on the same volume as your 
operating system. The space you allocate to the PASSUORD data 
set must be contiguous^ that is» its DSCB must indicate only one 
extent. The amount of space you allocate depends on the number 
of data sets your installation uiants to protect. Each entry in 
the PASSUORD data set requires 132 bytes of space. The 
organization of the PASSUORD data set is physical sequential » 
the record format is unblocked^ fixed-length records (RECFM=F). 
Each records uihich forms the data area» is 80 bytes long 
(LRECL=80,BLKSIZE=80)^ and is preceded by a 52-byte key 
(KEYLEN=52). The key area contains the fully qualified data set 
name of up to 44 bytes and a password of one to eight bytes* 
left justified Mith blanks added to fill the areas. The 
password assigned may be from one to eight alphameric characters 
in length. DADSM and Common VTOC Access Facility Diagnosis 
Gu i de and DADSM Diagnosis Reference describe the PASSUORD data 
set record format. 

Note: For data sets on magnetic tape designed according to the 
specifications of the International Organization for 
Standardization (ISO) 1001-1979 or the equivalent American 
National Standards Institute (ANSI) X3.27-1978» do not include 
generation and version numbers as part of generation data set 
names. The generation and version numbers are not included as 
part of the names in the tape labels* and are ignored if 
included in the PASSUORD data set. 

You can protect the PASSUORD data set itself by creating a 
password record for it when your program initially builds the 
data set. Thereafter* the PASSUORD data set cannot be opened 
(except by the operating system routines that scan the data set) 
unless the operator enters the password. 

Note: If a problem occurs on a password-protected system data 
set* maintenance personnel must be provided with the password in 
order to access the data set and resolve the problem. 



CREATING PROTECTED DATA SETS 



A data definition (DD) statement parameter (LABEL=) may be used 
to indicate that a data set i s to be password-protected. For 
data sets on DASD* an alternative method is to use the PROTECT 
macro instruction for a previously allocated data set. A data 
set may be created and the protection indicator set in its label 
without entering a password record for it in the PASSUORD data 
set. 

Operating procedures at your installation must ensure that 
password records for all data sets currently password-protected 
are entered in the PASSUORD data set. Installations where 
independent computing systems share common DASD resources must 
ensure that PASSUORD data sets on all systems contain the 
appropriate password records for any protected data set on 
shared DASD. 

Under certain circumstances* the order in which data sets are 
allocated and deallocated from multiple systems on shared DASD 
may result in loss of password-protection. For example* if an 
unprotected data set is allocated and opened by a user on System 
A and then scratched by a different user on System B* the first 
user is given a "window" to the unallocated (free) area. If any 
data set* protected or unprotected* is allocated in that space 
by a user on either system during the time the "window" is open* 
the new data set has no protection from the user with the 
"window," 

Uhile the allocation disposition is still NEU* a 
password-protected data set can be used without supplying a 
password. However* after the data set is deallocated* any 
subsequent attempt to open will result in termination of the 
program unless the password record is available and the correct 
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passMord is supplied. Note that> if the protection mode is 
NOPWREAD and the request is to open the data set for input or 
read backNard» no password Mill be required. 

Tape Voluines Containing More Than one Password-Protected Data Set 

to password protect a data set on a tape volume containing other 
data sets^ you must password protect all the data sets on the 
volume. (Standard labels — SL» SUL» AL» or AUL — are required. 
See Magnetic Tape Labels and File Structure for definitions of 
these label types and the protection-mode indicators that can be 
used.) 

If you issue an OPEN macro instruction to create a data set 
following an existing^ password-protected data set, the password 
of the existing data set will be verified during open processing 
for the new data set. The password supplied must be associated 
with a PWWRITE protection-mode indicator. 



PROTECTION FEATURE OPERATING CHARACTERISTICS 



The topics that follow provide information concerning actions of 

the protection feature in relation to termination of processing, 

volume switching, data set concatenation, SCRATCH and RENAME 

functions, and counter maintenance. 



Termination of Processing 

Processing is terminated when! 



Volume Switching 



1. The operator cannot supply the correct password for the 
protected data set being opened after two tries. 

2. A password record does not exist in the PASSMORD data set 
for the protected data set being opened. 

3. The protection-mode indicator in the password record, and 
the method of I/O processing specified in the Open routine 
do not agree, for example, OUTPUT specified against a 
read-only protection-mode indicator. 

4. There is a mismatch in data set names for a data set 
involved in a volume switching operation. This is discussed 
in the next paragraph. 



The system ensures a continuation of password protection when 
volumes of a mult i volume data set are switched. It accepts a 
newly-mounted tape volume, to be used for input, or a 
newly-mounted direct access volume, regardless of its use, if 
these conditions are met: 

• The data set name in the password record for the data set is 
the same as the data set name in the JFCB. (This ensures 
that the problem program has not changed the data set name 
in the JFCB since the data set was opened.) 

• The protection-mode indicator in the password record is 
compatible with the processing mode and a valid password has 
been supplied. 

The system accepts a newly-mounted tape volume to be used for 
output under any of these conditions^ 

• The security indicator in the HDRl label indicates password 
protection, the data set name in the password record is the 
same as the data set name in the JFCB, and the 
protection-mode indicator is compatible with the processing 
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mode. (If the data set name in the JFCB has been changed* a 
neM passMord is requested from the operator.) 

The security indicator in the HDRl label does not indicate 
passMord protection. (A neM label Mill be Nritten Mith the 
security indicator indicating passMord protection.) 

Only a volume label exists. (A HDRl label Mill be Mritten 
Mith the security indicator indicating passMord protection.) 



Data Set concatenation 



A passHord is requested for every protected data set that is 
involved in a concatenation of data sets» regardless of Mhether 
the other data sets involved are protected or not. 






O 
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SCRATCH and rename Functions 



To delete or rename a protected data set» it is necessary that 
the job step making the request be able to supply the;, password. 
The system first checks to see if the job step is currently 
authorized to write to the data set. If not» message IEC301A is 
issued to request the password. The password provided must be 
associated with a "WRITE" protection-mode indicator. 



Counter Maintenance 









The operating system increments the counter in the password 
record on each usage» but no overflow indication will be given 
(overflow after 65>535 openings). You must provide a counter 
maintenance routine to check and» if necessary^ reset this 
counter. 

USING THE PROTECT MACRO INSTRUCTION TO MAINTAIN THE PASSWORD DATA SET 

To use the PROTECT macro instruction* your PASSUORD data set 
must be on the system residence volume. The PROTECT macro can 
be used to^ 

• Add an entry to the PASSklORD data set. 

• Replace an entry in the PASSWORD data set. 

• Delete an entry from the PASSWORD data set. 

• Provide a list of information about an entry in the PASSWORD 
data set; this list will contain the security counter* 
access type* and the 77 bytes of security information in the 
"data area" of the entry. 

In addition* the PROTECT macro updates the DSCB of a protected 
direct access data set to reflect its protection status* this 
feature eliminates the need for you to use job control language 
whenever you protect a data set. 

PASSWORD DATA SET CHARACTERISTICS AND RECORD FORMAT UHEN YOU USE THE PROTECT MACRO 
INSTRUCTION 

When you use the PROTECT macro > the record format and 
characteristics of the PASSWORD data set are no different from 
the record format and characteristics that apply when you use 
your own routines to maintain it. 

Number of Records for Each Protected Data set 

When you use the PROTECT macro* the PASSWORD data set must 
contain at least one record for each protected data set. The 
password (the last 8 bytes of the "key area") that you assign 
when you protect the data set for the first time is called the 
control password. In addition* you may create as many secondary 
records for the same protected data set as you need. The 
passwords assigned to these additional records are called 
secondary passwords. This feature is helpful if you want 
several users to have access to the same protected data set* but 
you also want to control the manner in which they can use it. 
For example: One user could be assigned a password that allowed 
the data set to be read and written* and another user could be 
assigned a password that allowed the data set to be read only. 

Note: The PROTECT macro will update the protection-mode 
indicator in the format-1 DSCB in the protected data set only 
when you issue it for adding* replacing* or deleting a control 
password. 
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Protect fon-Mode indicator 



You can set the protection-mode indicator in the password record 
to four different values* 

• X'OO* to indicate that the password is a secondary password 
and the protected data set is to be read only (PMREAD). 

• X*80* to indicate that the password is the control password 
and the protected data set is to be read only (PMREAD). 

• X*01* to indicate that the password is a secondary password 
and the protected data set is to be read and written 
(PWREAD/PWWRITE). 

• X*81* to indicate that the password is the control password 
and the protected data set is to be read and written 
(PWREAD/PWWRITE). 

Because of the sequence in which the protection status of a data 
set is checked^ the following defaults will occur: 



If control password Is: 

1. PWREAD/PWWRITE or 
PWREAD/NOWRITE 

2. NOPWREAD/PWWRITE 



Secondary password must be: 

PWREAD/PWWRITE or 
PWREAD/NOWRITE 

NOPWREAD/PWWRITE 



If the control password is set to either of the settings in item 
1 above» the secondary password will be set to PWREAD/PWWRITE if 
you try to set it to NOPWREAD/PWWRITE. 

If the control password is changed from either of the settings 
in item 1 to the setting in item 2 above> the secondary password 
will be automatically reset to NOPWREAD/PWWRITE. 

If the control password is changed from the setting in item 2 to 
either of the settings in item 1 above* the secondary password 
is set by the system to PWREAD/PWWRITE. 

Because the DSCB of the protected data set is updated only when 
the control password is changed* you may request protection 
attributes for secondary passwords that conflict with the 
protection attributes of the control password. 



\J 
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PROTECT HACRO SPECIFICATION 

The format is! 



[svmboll 


PROTECT 


parameter list address 



parameter list address — A-tvpe address* (2-12)* or (1) 
indicates the location of the parameter list. The 
parameter list must be set up before the PROTECT macro is 
issued. The address of the parameter list may be passed in 
register 1* in any of the registers 2 through 12* or as an 
A-type address. The first byte of the parameter list must 
be used to identify the function (add* replace* delete* or 
list) you want to perform. See Figure 26 on page 117 
through Figure 29 on page 119 for the parameter lists and 
codes used to identify the functions. 



116 MVS/370 System Programming Library! Data Management 






X»01» 


1 00 00 00 


♦ Length of data set name 


5 Pointer to data set name 


8 00 


9 00 00 00 


12 00 


13 Pointer to control password 


16 Number of volumes 


17 Pointer to volume list 


20 Protection code 


21 Pointer to new password 


2^ String length 


25 Pointer to string 



^r^^ 
^%^' 



X»01» 

Entry code indicating ADD function. 

4 Length of data set name. 

5 Pointer to data set name. 

13 Pointer to control password. 

The control password is the password assigned when the data set was placed 
under protection for the first time. The pointer can be 3 bytes of binary 
zeros if the new password is the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as protected^ 
you have to specify the number of volumes in this field. A zero indicates that 
the catalog information should be used. 

17 Pointer to volume list. 

If the data set is not cataloged and you want to have it flagged as protected* 
you provide the address of a list of volume serial numbers in this field. 
Zeros indicate that the catalog information should be used. 

20 Protection code. 

A one-byte number indicating the type of protection* X'OO" indicates default 
protection (for the ADD function; the default protection is the type of 
protection specified in the control password record of the data set); X*01* 
indicates that the data set is to be read and written; X*02* indicates that the 
data set is to be read only; and X*03* indicates that the data set can be read 
without a password* but a password is needed to write into it. The PROTECT 
macro will use the protection code value* specified in the parameter list* to 
set the protection-mode indicator in the password record. 

21 Pointer to new password. 

If the data set is being placed under protection for the first time* the new 
password becomes the control password. If you are adding a secondary entry* 
the new password is different from the control password. 



2^ String length. 

The length of the character string (maximum 77 bytes) that 
the optional information field of the password record. If 
add information* set this field to zero. 



you 
you 



want to place 
don't want to 



in 



25 Pointer to string. 

The address of the character string that 
information field. If you don't want to 
field to zero. 

Figure 26. Parameter List for ADD Function 



is going to be 
add additional 



put in the optional 
information* set this 



Chapter 5. Password Protecting Your Data Sets 117 



X'02V 


1 00 00 00 


4 Length of data set name 


5 Pointer to data set name 


8 00 


9 Pointer to current password 


12 00 


13 Pointer to control password 


16 Number of volumes 


17 Pointer to volume list 


20 Protection code 


21 Pointer to new password 


24 String length 


25 Pointer to string 



.J 



X'02'. 

Entry code indicating REPLACE function. 

4 Length of data set name. 

5 Pointer to data set name. 

9 Pointer to current password. 

The address of the password that is going to be replaced. 

13 Pointer to control password. 

The address of the password assigned to the data set when it was first placed 
under protection. The pointer can be set to 3 bytes of binary zeros if the 
current password is the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as protected* 
you have to specify the number of volumes in this field. A zero indicates that 
the catalog information should be used. 

17 Pointer to volume list. 

If the data set i s not cataloged and you want to have it flagged as protected* 
you have to provide the address of a list of volume serial numbers in this 
field. If this field is zero* the catalog information will be used. 

20 Protection code. 

A one-byte number indicating the type of protection? X'OO' indicates that the 
protection is default protection (for the REPLACE function the default 
protection is the protection specified in the current password record of the 
data set); X'Ol* indicates that the data set is to be read and written; X*02* 
indicates that the data set is to be read only; and X*03* indicates that the 
data set can be read without a password* but a password is needed to write into 
the data set. 

21 Pointer to new password. 

The address of the password that you want to replace the current password. 

24 String length. 

The length of the character string (maximum 77 bytes) that you want to place in 
the optional information field of the password record. Set this field to zero 
if you don't want to add additional information, 

25 Pointer to string. 

The address of the character string that is going to be put in the optional 
information field of the password record. Set the address to zero if you don't 
want to add additional information. 

Figure 27. Parameter List for REPLACE Function 
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X'03' 


1 


00 00 00 




4 


Length of data set name 


5 


Pointer to 


data set name 


8 


00 


9 


Pointer to 


current password 


12 


00 


13 


Pointer to 


control password 


16 


Number of volumes 


17 


Pointer to 


volume list 



X'03'. 

Entry code indicating DELETE function. 

4 Length of data set name. 

5 Pointer to data set name. 

9 Pointer to current password. 

The address of the password that you want to delete. You can delete either a 
control entry or a secondary entry. 

13 Pointer to control password. 

The address of the password assigned to the data set when it was placed under 
protection for the first time. The pointer can be 2 bytes of binary zeros if 
the current password is also the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as protected* 
you have to specify the number of volumes in this field. A zero indicates that 
the catalog information should be used. 

17 Pointer to volume list. 

If the data set is not cataloged and you want to have it flagged as protected* 
you have to provide the address of a list of volume serial numbers in this 
field. If this field is zero* the catalog information will be used. 

Figure 28. Parameter List for DELETE Function 



X'04' 


1 Pointer to 80-byte buffer 


4 Length of data set name 


5 Pointer to data set name 


8 00 


9 Pointer to current password 



X'0<i'. 

Entry code indicating LIST function. 

1 Address of 80-byte buffer. 

The address of a buffer where the list of information can be returned to your 
program by the macro instruction. 

4 Length of data set name. 

5 Pointer to data set name. 

9 Pointer to current password. 

The address of the password of the record that you want listed. 

Figure 29. Parameter List for LIST Function 
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RETURN CODES FROM THE PROTECT MACRO 



Uhen the PROTECT macro finishes processing* register 15 contains 
one of the follouing return codes! 

Code Meaning 

0(00) The updating of the PASSUORD data set Mas successfully 
completed. 

4(04) The PASSUORD of the data set name Mas already in the 
passMord dat^t set. 

8(08) The password of the data set name Mas not in the 
PASSUORD data set. 

12(00) A control password is required or the one supplied is 
incorrect. 

16(10) The supplied parameter list Mas incomplete or 
incorrect. 

20(14) There Mas an I/O error in the PASSUORD data set. 

24(18)^ The PASSUORD data set Mas full. 

28(10) The validity check of the buffer address failed. 

32(20)* The LOCATE macro failed. LOCATE* s return code is in 
register 1, and the number of indexes searched is in 
register 0. 

36(24)2 The OBTAIN macro failed. OBTAIN's return code is in 
register 1. 

40(28)2 The DSCB could not be updated. 

44(20) The PASSUORD data set does not exist. 

48(30)2 Tape data set cannot be protected. 

52(32)2 Data set in use. 

^For this return code* a message is Mritten to the console 
indicating that the PASSUORD data set is full. 

2For this return code> the PASSUORD data set has been updated* 
but the DSCB has not been flagged to indicate the protected 
status of the data set. 
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CHAPTER 6. EXIT ROUTINES 






This chapter discusses hoM installation-Mri tten modules can^ 

• Take control before and after direct access device storage 
management (DADSM) processing 

• Take control during Open for a DCB 

• Determine uihether a missing data set control block (such as 
for a data set that has been moved to another volume) can be 
restored to a volume 

• Recover from errors that may occur during the opening* 
closing* or handling of an end-of-volume condition for a 
data set associated Mith the user's task 

This chapter also describes houi user programs can: 

• Identify a specific tape volume to be requested in place of 
a nonspecific (scratch) tape volume 

• Verify that an IBN-standard labeled tape selected by open or 
EOV should* in fact* be used* and whether certain security 
checks nay be bypassed (this exit is for authorized programs 
only) 

Note: For information on IBM-supplied exits for tapes with 
International Organization for Standardization (ISO) or American 
National Standard labels* refer to MVS/370i Magnetic Tape Labels 
and File Structure, 



#**>, 
^^/ 



,; 



DADSM PREPROCESSING AND POSTPROCESSING EXIT ROUTINES 



THE EXIT NODULES 



There are exit routines to enable an installation~wri tten module 
to take control before and after DADSM processing. An exit 
parameter list is used to communicate with DADSM. The format of 
this parameter list is shown in Figure 30 on page 123. 



All of the DADSM functions (allocate* extend* scratch* partial 
release* and rename) have a common preprocessing exit routine 
and a common postprocessing exit routine that the installation 
exit routine can replace. These exit routines enable you to 
gain control before and after DADSM processing. The 
preprocessing exit routine module is IGGPREOO* the 
postprocessing exit routine module is IGGPOSTO. Each is used by 
all the DADSM functions listed above. The modules reside in- 
SYSl.LPALIB. You can use System Modification Program (SMP) to 
replace the IBM-supplied exit routine modules with an 
installation exit routine you write. 



THE EXIT ENVIRONMENT 



The exit routines are given control in supervisor state and 
protect key zero with no locks held. The exit routines must be 
reentrant. System enqueues will have been issued either by 
DASDM or by the programs that invoke DADSM* to serialize system 
functions. These enqueues may prevent other system services 
from being invoked. In particular* dynamic allocation* OPEN* 
CLOSE* EOV* LOCATE* and other DADSM functions may not be issued 
because of an enqueue on the SYSZTIOT resource. If the exit 
routines require access to an installation data set* the control 
blocks required to access that data set (DCB* DEB) should be 
built during system initialization (IPL/NIP). RACF macros may 
be invoked from the exit routines. 
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UHEN XGGPREOO GETS CONTROL 



The preprocessing exit routine* IGGPREOO* is given control fl^^ 

before the first VTOC update and after initial validity '\^ ^ 

checking. Input to XGGPREOO is a parameter list* mapped by 

macro lECIEXPL* that contains addresses of input data and a 

function code that identifies the DADSM function. XGGPREOO is 

given control once for each volume in the volume list supplied 

to scratch and rename. A field in the parameter list, XEXRSVMD, 

may be used to pass data from the preprocessing exit routine to 

the postprocessing exit routine. 

A zero return code from XGGPREOO indicates the DADSM function 
may proceed. 



REJECTING A DADSN REQUEST 



A preprocessing exit routine may reject a DADSM request* in 
Mhichcase an X/0 error return code is generated for all 
functions except allocate and extend. A return code of 4 or 8 
from XGGPREOO to allocate will cause allocate to return X'B^' or 
X'BO'* respectively* to its caller in Register 15. Scheduler 
allocation will treat a X'B4' as a conditional rejection of the 
allocate request only for the volume being processed. Xf the 
allocate request is not for a specific volume* another volume 
may be chosen and the allocate function retried. Scheduler 
allocation will treat a X'BO' return code from allocate as an 
unconditional rejection of the allocate request. Xf the 
allocate request is rejected* the preprocessing exit routine can 
put a reason code in the parameter list field* XEXREASN* and the 
code will be returned by allocate to its caller* together with 
the X'BO' or X'B4* return code in Register 15. The reason code 
will appear in the JCL error message* if the allocate request is 
not retried. A nonzero return code from XGGPREOO to extend will 
cause extend to return an error return code of X'FFFF FFEC to 
its caller. If the caller is End-of-Volume, an E37-0C abend 
will be issued. 



PASSING A MODEL FORMAT- 1 DSCB 



The preprocessing exit for allocate and extend on a new volume 
may return* in the parameter list field XEXFMTl* the address of 
the data portion of a model format-1 DSCB* starting with field 
DSIFMTXD. The DSCB will be moved to the allocate or extend work 
area before building the format-1 DSCjB. The only fields that 
may be nonzero in the area are the DSIREFD (the 
data-last-referenced field) and fields currently unused. All 
other fields will be initialized by allocate or extend. lEXFMTl 
may not be supplied by IGGPREOO for a VIO allocate request 
(indicated by flag* lEXVXO* set to one), or if a partial DSCB 
instead of a JFCB has been supplied to allocate (indicated by 
flag, XEXMFl, set to one). In the latter case* lEXFMTl is 
passed to IGGPREOO initialized to the address of the DSIFMTID 
field of the partial format-1 DSCB (supplied to allocate by its 
caller) in the allocate work area* and DSIREFD may be 
initialized by IGGPREOO. If extend was successful* lEXFMTl is 
zeroed out prior to taking the post-exit* IGGPOSTO. 



UHEN IGGPOSTO GETS CONTROL 



The postprocessing exit module* IGGPOSTO* is given control after 
a DADSM function has been completed or attempted. IGGPOSTO is 
given control if IGGPREOO was given control, whether the DADSM 
function was successful or not. IGGPOSTO is not given control 
if IGGPREOO was not given control* or if the DADSM function 
terminated abnormally. IGGPREOO may establish a recovery 
routine* if required* to clean up system resources. The DADSM 
recovery routine does not give IGGPOSTO control. 



o 
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Input to IGGPOSTO is the same parameter list passed to IGGPREOO. 
No return codes from IGGPOSTO are defined. 
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^f^, 

^^^'' 



Name 



Offset 



Bytes 



i^, 

V-/'' 



lEXID 


00(00) 


4 


lEXLENG 


04(04) 


1 


lEXFUNC 


05(05) 


1 


lEXALL 






lEXEXT 






lEXSCR 






lEXPR 






lEXREN 






lEXEXTCD 


06(06) 


1 



IEXFLAG 
lEXENQ 
lEXVIO 
lEXMFl 


07(07) 


1 

.1 


lEXREASN 

lEXUCB 
lEXPTRl 


08(08) 

12(0C) 
16(10) 


... X xxxx 

2 

2 

4 
4 


IEXPTR2 


20(14) 


4 



lEXDSN 
lEXFMTl 



IEXFMT2 

lEXRSVOO 
lEXEXTBL 



lEXDCC 
lEXRSVUD 



24(18) 
28(1C) 



32(20) 

36(24) 
40(28) 



44(2C) 
48(30) 



X»02» 
X'04» 
X»81» 



Description 

EBCDIC 'lEPL' 

Length of parameter list 

DADSM function code* 

X'Ol'-Allocate 

X»02'-Extend 

X»03'-Scratch 

X*04*-Partial Release 

X»05»-Rename 

Extend code 

X*01* Extend data set on 

current volume 

Extend an OS catalog 

on current volume 

Extend data set on 

neM volume 

Extend VSAM data space 

on current volume 
Flag byte 

VTOC is enqueued upon entry 
VIO data set 

lEXFMTl points to DXIFMTID of a 
partial format-1 DSCB (partial 
DSCB passed as input to Allocate* 
and not JFCB is not available). 
Reserved 

Installation reject reason code 
Reserved 
Address of UCB 
Address of the following* 

- JFCB (Allocate* Extend* Partial Release) 

- Scratch/Rename input parameter list 
(in user storage) 

Address of the folloMing? 

- DSAB list (ISAM Allocate) 

- DEB (Extend on old volume) 

- DCB (Partial Release) 

- Current volume list entry 
(Scratch/Rename) 

Address of the data set name 

Address of the 96- 

byte data portion of format-1 

DSCB (pre- and post-exit for 

partial release; post-exit for 

scratch). May be supplied by 

pre-exit of allocate* and extend 

on neM volume* to serve as a 

model if lEXMFl and lEXVIO are 

zero* postexit for allocate 

Address of format-2 DSCB 

(ISAM Allocate post exit) 

Reserved 

Address of extent table 

(pre- and post-exit for scratch 

and partial release* post-exit 

for allocate and extend) 

DADSM completion code 

(post exit) 

Reserved uiord for use by 

installation exit 



Figure 30. Format of the DADSM Preprocessing "dnd Postprocessing Exit Parameter List 
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SYSTEM CONTROL BLOCKS 

The DADSM installation exit parameter list contains the address 
of system control blocks. The mapping macros of those control 
blocks are listed beloM together Mith the name of the system 
library in Mhich they reside. One of the macros* ICVARXNT* is 
only supplied Mith the optional material. 

Macro Control Block Location 

lECSDSLl DSCB SYSl.AMODGEN 

lEFUCBOB UCB SYSl.AMODGEN 

lEFJFCBN JFCB SYSl.AMODGEN 

IHADSAB DSAB SYSl.MACLIB 

lEZDEB DEB SYSl.MACLIB 

IHADCB DCB SYSl.MACLIB 

lEFTIOTl TIOT SYSl.AMODGEN 

ICVARXNT Extent Table Optional Material 

lECIEXPL DADSM installation SYSl.MACLIB 
exit parameter list 

There is no mapping macro for the SCRATCH/RENAME parameter list 
or the associated volume list. 

For extend and partial release* the address of the JFCB passed 
to the user exit points to a copy of the real JFCB. Updating 
the copied JFCB Mill not result in a corresponding change to the 
real JFCB. 

During EXTEND of a VSAM data set* the exit is passed the address 
of a dummy DEB. This DEB doe? not contain any EXTENT 
information. 

REGISTERS AT ENTRY TO EXITS 

At entry to your exit routine* register contents arts as.folloNs: 

Register Contents 

1 Address of the exit parameter list 

13 Address of an 18-Nord save area 

14 Return address to DADSM 

15 Address of your exit routine 

REGISTERS AT RETURN TO DADSM 

Mhen you return to DADSM* register contents must be as folloNS^ 

Register Contents 

0-14 Same as on entry to your exit routine 

15 A return code from IGGPREOO 

The return codes and their meanings are as folloMS" 

Code Meaning 

Indicates that you Mant the DADSM request to be 
processed 

4 Indicates that no DADSM request for the current volume 
i s to be processed 

8 Indicates that you do not Mant the DADSM request to be 
processed 
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THE EXIT NODULE 



There is an exit that enables an installation-Mri tten module to 
take control during Open for a DCB. An exit parameter list is 
used by open processing to communicate Mith the exit module. 
The format of the parameter list is shoMn in Figure 31 on page 
126. 



OPEN has an exit module that the installation can replace. This 
module is IFGOEXOB> which resides in load module IGCOOOII. The 
load module resides in SYSl.LPALIB. You can use System 
Modification Program (SMP) to replace the IBM-supplied exit 
module with an installation exit you write. 



THE EXIT ENVIRONMENT 



IFGOEXOB is given control in supervisor state and protect key 
zero Mith no locks held. System enqueues Mill have been issued 
to serialize system functions. These enqueues may prevent other 
system services from being invoked. In parti cular» dynamic 
allocation* OPEN* CLOSE* EOV* and DADSM functions should not be 
invoked because of an enqueue on the SYSZTIOT resource. If the 
exit requires access to an installation data set* the control 
blocks required to access that data set (DCB* DEB) should be 
built during system initialization (IPL/NIP). RACF macros may 
be invoked from the exit. 



OPEN PROCESSING BEFORE IFGOEXOB GETS CONTROL 






The exit module* IFGOEXOB* is given control Mhenever OPEN 
processes a DCB. The exit is taken after the folloNing 
functions have been performed for the DCB. 

• DASD data sets 

-- Volume mounted 

— Format-1, -2* and -3 DSCBs read 

— Forward merge from format-1 DSCB to JFCB 

• Tape data sets 

— Volume mounted 

— Header labels verified 

— Forward merge from header labels to JFCB 

• All data sets 

— ForMard merge from JFCB to DCB 

— User DCB OPEN exit (if any) taken 

— RACF or password verification processing 



OPEN PROCESSING AFTER IFGOEXOB GETS CONTROL 



The following functions have not yet been performed at the time 
the exit is given control for the DCB. 

• Reverse merge from DCB to JFCB (not all fields ar& merged) 

• Reverse merge from JFCB to format-1 DSCB for DASD data sets 
(not all fields are merged) 

• Header labels written (for output tape data set) 
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Access-method-dependent processing (obtain buffers* getmain 

and build lOBs and DEB) 

r 

Write JFCB 

Mrite format-1 DSCB 



GETTZN6 CONTROL FROM OPEN 



The exit is 
tMo or more DCB 
invocation of OPEN. 



given control for each DCB being opened* even when 
DCBs are being opened* in parallel* uiith one 



The exit is given control from OPEN (SVC 19) and OPEN TYPE=J 
(SVC 22). The exit is given control from end-of-volume (EOV; 
SVC 55) and from force-end-of-volume (FEOVj SVC 31) when a 
concatenation of two sequential data sets with unlike attributes 
is being processed. In this case* EOV gives control to CLOSE* 
which gives control to OPEN. The exit i s not given control 
from EOV when a concatenation of two sequential data sets with 
like attributes is being processed. In this case* EOV does not 
give control to CLOSE and OPEN. A request by the user program 
for concatenation with unlike attributes is shown in the DCB by 
flag DCBOFPPC (bit 4; mask X'08') in field DCBOFLGS being set to 
one. 



DATA THAT OPEN PASSES TO THE EXIT 



Name 

OIEXL 

OIEXOOPT 

OIEXRSVD 

OIEXOOUT 

OIEXOOIN 

OIEXOUPD 

OIEXOINO 

OIEXORDB 

OIEXOINP 

OIEXUKEY 

OIEXLTH 

OIEXUDCB 

01 EXP DCB 

01 EX JFCB 
OIEXDSCB 

OIEXTIOT 
OIEXUCB 



Offset 

00(00) 
00(00) 



01(01) 
02(02) 
04(04) 

08(08) 

12 (OC) 
16(10) 

20(14) 
24(18) 



The parameter list mapped by macro lECOIEXL is supplied to the 
installation exit. It contains data and the addresses of 
control blocks that may be of interest to the exit. 

The format of the parameter list is shown in Figure 31. 



Bytes Description 

DCB Open installation exit 
parameter li st 

1 Open option (last 4 bits). 
1111 X'FO' first 4 bits reserved. 

1111 15 output 
111 7 outi n 
1. . 4 update 
.11 3 inout 
..1 1 read backward 
... input 

User protect key. Key of user DCB 

Length of OIEXL 

Address of user DCB 

in user protect key (OIEXUKEY) 

Address of protected 

copy of DCB used by OPEN 

Address of JFCB 

Address of data portion of 

format-1 DSCB 

Address of TIOT entry 

Address of UCB 






Figure 31. Format of OPEN Exit Parameter List 



Note that two DCB addresses are supplied. OPEN maintains a 
protected copy of the user DCB. OPEN's copy of the DCB may be 
used to test DCB fields. If any modification is made to the 
DCB* both the user DCB and OPEN's protected copy must be 
updated. The protect key of the user DCB is supplied in the 
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exit parameter list. This protect key must be used to either 
fetch from or store into the user DCB. 

Care should be taken to determine the type of DCB and device 
passed to the exit before testing access-method or 
device-dependent fields in the DCB. The sample exit shoMn in 
Appendix E gives an example of isolating a QSAM DCB being opened 
to a DASD or tape device. 

The JFCB address supplied to the exit points to a copy of the 
JFCB that is in OPEN*s work area. There may be other JFCBs 
associated with the OPEN » if ISAM or concatenated partitioned 
data sets are being opened. 

In the case of BDAMy ISANy and concatenated partitioned data 
sets» the UCB» uihose address is supplied to the exit» may not be 
the only UCB associated Mith the DCB being opened. The UCB 
should not be modified. 

The TIOT address supplied i s of a TIOT entry (TIOENTRY label in 
the lEFTIOTl macro). In the cases of ISAM and concatenated 
partitioned data setsy other TIOT entries may be associated with 
the DCB being opened. If concatenation of unlike attributes is 
being processed^ the TIOT entry may have a blank DDNAME field. 

The format-1 DSCB passed to the exit is in the OPEN Mork area. 
The address is of the field» DSIFMTID. There may be format-2 
and -3 DSCBs associated Mith the format-1 DSCB. There may be 
other format-1 through -3 DSCBs associated Mith the DCB being 
opened in the cases of ISAM» BDAMy and concatenated partitioned 
data sets. If the OPEN is to the VTOC, a format-4 DSCB address 
is passed to the exit; this can be determined by testing field 
DSIFMTID for a value of X*F4*» or the data set name in the 
JFCBDSNM field of 44X»04». 






DEFAULTING BUFFER NUMBER FOR QSAM 



nODZFYZNG THE JFCB 



If a value has not yet been supplied^ the exit may be used to 
supply an installation-determined value for DCBBUFNO (number of 
buffers) for QSAM DCBs, 

A sample exit program that does this is shoMn in Appendix E. 

It may not be advisable to override a nonzero value of DCBBUFNO 
without knoMing Mhat dependency the user program has on that 
value. DCBBUFNO can not be overridden Mhen a buffer pool control 
block address exists in the DCB field* DCBBUFCA; this indicates 
buffers have been acquired before OPEN. DCBBUFCA is set to one 
(and not zero) if no buffer pool control block address exists. 



Whenever the JFCB is modified* code 4 should be returned to 
OPEN. This Mill cause OPEN to rewrite the JFCB. The JFCB should 
not be modified if the user program has set JFCNURIT (bit 4) in 
byte JFCBTSDN as it indicates the JFCB should not be written. 

A sample exit program that modifies the JFCB is shoMn in 
Appendix E. 



REQUESTING PARTIAL RELEASE 



An example of modifying the JFCB in OPEN*s work area is used to 
set the bits to 1 indicating partial release has been requested: 
JFCRLSE (bits and 1; mask X'CO') in byte JFCBINDl. This 
should be done only for DASD physical sequential or partitioned 
data sets opened for OUTPUT or OUTIN and processed by (1) EXCP 
with a 5-word device-dependent section present in the DCB» (2) 
BSAM* or (3) QSAM. 
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Care should be taken in modifying the JFCB release bits. For 
example^ a data set that is opened for output many times» 
Mriting varying amounts of data each time» may have to extend 
after each OPEN» resulting in many small extents and» perhaps^ 
reaching the 16-extent limit. This could result in a B37 abend. 

Care should also be taken in setting the JFCBSPAC bits to define 
the space quantity units when the partial release flag> 
JFCBRLSEy is also set on. A cylinder allocated extent may be 
released on a track boundary Mhen JFCBSPAC does not indicate 
cylinder units or average block length units Nith ROUND 
specified. This will cause the cylinder boundary extent to 
become a track boundary extents thereby losing the performance 
advantage of cylinder boundary extents. Zeroing the release 
indicator and increasing secondary allocation quantity Mhen« for 
example* the data set has extended a large number of times* may 
prevent such a B37 abend. Setting the release indicator could 
result in more space being made available to other users sharing 
the volume. 



UPDATING THE SECONDARY SPACE DATA 



The JFCB may also be modified by updating the secondary space 
data. Byte JFCBCTRI contains the space request type coded in 
the DD statement, or merged from the format-1 DSCB. Field 
JFCBSQTY contains the amount of secondary space (in either 
tracks, cylinders* or average block units). Field JFCBPQTY 
contains the amount of primary space (in either tracks* 
cylinders* or average block units). 

Setting the contiguous bit (JFC0NTI6) to zero may prevent an 
out-of-space ABEND where there is enough space* but not enough 
contiguous space* to satisfy a request to extend the data set. 






REGISTERS AT ENTRY TO IFGOEXOB 

At entry to the exit* register contents ere as follows* 

Register Contents 

1 Address of the DCB OPEN installation exit parameter 
list 

13 Address of an 18 word save area 

14 Return address to OPEN 

15 Address of the entry point to IFGOEXOB 

REGISTERS AT RETURN TO OPEN 

Mhen you return to OPEN* register contents are as follows^ 

Register contents 

0-14 Same as on entry to the exit 

15 Set to 4 if the JFCB has been modified. Set to if 
the JFCB has not been modified 

OPEN/EOV INSTALLATION EXIT FOR FORHAT-1 DSCB NOT FOUND 

The function of the Format-1 DSCB-not-found installation exit in 

OPEN and EOV is to determine if a missing DSCB (such as a data 

set which has been migrated to another volume) can be restored J'~^^ 

to the volume. If your exit module restores the DSCB* it m ) 

indicates this when it returns control to the control program. \w./ 

The exit module* IFGOEXOA* is given control whenever OPEN or EOV 

fails to find a format-1 DSCB on a volume. There is an 
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IBM-supplied exit module^ IFGOEXOA» in SYSl.LPALIB. If you wish 
to use your OMn exit module* you must replace IFGOEXOA. Your 
exit module must have an entry point name of IFGOEXOA. If you 
do not Mrite your oun exit module* processing continues normally 
as the IBM-supplied exit returns a zero return code. 

The exit is taken even under conditions Mhere abnormal 
termination ordinarily Mould not occur. Tuo examples of these 
conditions folloM^ 

1. Uhen you have specified DISP=MOD and error recovery 
processing is taking place because the last volume specified 
in the JFCB does not contain the DSCB* but an earlier volume 
does. For this case* if your return code from IFGOEXOA is 
zero or if your return code is 4 and the DSCB has not been 
restored, OPEN and EOV search the other volumes for the DSCB 
after the exit is taken. 

2. Another condition occurs during EOV output when space has 
not yet been allocated on the new volume. Space is 
allocated after the exit is taken if your return code from 
IFGOEXOA is zero or if your return code is^ and the DSCB 
has not been restored. 

Uhen a DSCB is not found* IFGOEXOA is given control as folloMS^ 

• In system protect key 5 (data management key) 

• In supervisor state 

• The system resource represented by the SYSZTIOT major name 
is enqueued for shared control (this ENQ prevents the exit 
from invoking system functions such as SCRATCH* RENAME* 
dynamic allocation* or LOCATE). 

Standard register linkage conventions are used when IFGOEXOA is 
given control as follows* 

Register contents 

If 0* entry was from OPEN (single volume data set) 
If C* entry was from OPEN (mult i volume data set) 
If F, entry was from EOV 

1 Address of parameter list 
2-12 Unpredictable 

13 Address of 18-word save area 

14 Return address 

15 Address of entry point IFGOEXOA 

The parameter list pointed to by register 1 consists of two 
fullwords. The first fullword contains the address of the UCB 
for the volume on which the DSCB was not found. The second 
fullword contains the address of the 44-byte data set name* left 
justified* and padded with blanks. Bit zero of the second 
fullword is set to one* indicating the last word in the 
parameter list. The data set name must not be modified by the 
exit. The parameter list* save area* and data set name are in 
protect key 5 virtual storage* which is not fetch protected. 
IFGOEXOA must be reenterable. All work areas obtained through 
GETMAIN must be released through FREEMAIN. The return from your 
module* IFGOEXOA* to OPEN or EOV must be made as follows^ 

• Using the return address passed to you in register 1<» 

• Registers 2-12 restored 

• In protect key 5 
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• In supervisor state 

• With a return code of 0» 4> or 8 in register 15 

The return code you set in register 15 has the following 
meanings: 



DATA HANAGEMENT ABEND INSTALLATION EXIT 



The abend installation exit provides the ability to recover from 
abnormal conditions that may occur during the opening^ closing* 
or handling of an end-of-volume condition for a non-VSAM data 
set associated uiith the user's task. 

Mhen an abnormal condition occurs* control passes to the DCB 
abend user exit routine* if one is provided* and processing 
continues as specified i n the DCB abend user exit routine. (The 
DCB abend user exit routine gives you some options regarding the 
actions you Mant the system to take Mhen a condition arises that 
may result in abnormal termination of your task. For additional 
information about the DCB abend user exit routine* see Data 
Management Serv i ces . ) However* if the DCB abend user exit 
routine is not specified* or specifies to abnormally terminate 
the task immediately* the system passes control to the abend 
installation exit. If a DCB abend user exit routine is not 
provided* control immediately passes to the abend installation 
ex i t . 



\j^ 



Code Meaning 

0(00) Processing continues normally. This return code is 

given if the exit does not restore the DSCB. Zero is 
the return code always given by the IBM-supplied exit 
module. 

4(04) The volume is searched one more time by OPEN or EOV 
for the DSCB. This return code is given if IFGOEXOA 
restores the DSCB to the volume. If the DSCB is again 
not found* IFGOEXOA is not given control and 
processing continues normally. 

8(08) The task is abnormally terminated without attempting 
to determine if DISP=MOD error recovery or allocation 
on the new volume should occur. This return code is 
given if IFGOEXOA encounters an error and you wish no 
further processing to occur. 

You should have IFGOEXOA establish its own error recovery 
environment (such as through an ESTAE)* intercept any 
indeterminate errors* and return to the control program with 
return code 8. Problem determination is the responsibility of 
your exit module. A wri te-to-programmer (MTO with routing code 
11) or a TPUT (if a TSO region) may be used to issue an 
informative message. 

During a parallel OPEN when two or more DCBs aret being opened at 

the same time* and two of the DCBs are opening the same data /f'"\ 

set* the DSCB may be missing. If IFGOEXOA is called for the 

first of the two DCBs and restores the DSCB* the channel program 

attempting to read the DSCB for the second DCB may have been 

executed before the restoration of the DSCB was complete. 

IFGOEXOA is then called for the second DCB even though the DSCB 

has already been restored. Return from IFGOEXOA with a return 

code 4 is appropriate in this case. 

IFGOEXOA is not given control when you are processing a VSAM 
data set with an ACB* however* it is given control when you are 
processing a VSAM data space with a DCB. IFGOEXOA is bypassed 
if the format-4 DSCB is not found on a volume* even if the OPEN 
is to the VTOC data set name (data set name of 44 bytes of 
X''04»). 



vy 
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^^. 

^lj^' 



IBM supplies an installation exit module^ IFG0199I in 
SYSl.LPALIBy that handles abend situations caused by tape 
positioning errors. IFG0199I alloMs you to retry tape 
positioning when you receive a system completion code 613^ 
return code 08 or OC. To perform recovery actions for data 
management abend situations (other than those caused by tape 
positioning errors)^ you can replace installation exit module 
IFG0199I by modifying the source code supplied in SYSl .SAMPLIB. 

IFG0199I receives control in protection key zero» supervisor 
state. IFG0199I checks the system completion code and the 
return code to determine whether the abend situation is the 
result of a tape positioning error. If the system completion 
code is other than 613 Mith return code 08 or 0C» control 
returns to the calling module with return code 0, indicating to 
continue with the abend. OtherMise» IFG0199I checks the counter 
in the 4-byte work area to determine if one attempt to 
reposition the tape has been made. If no attempt to reposition 
the tape has been made» IFG0199I issues a return code of 4» 



indicating to retry positioning, 
the tape has been made> IFG0199I 

to determine whether to 

specifies that 

return code of 



operator 
operator 
again » a 
the tape 



If one attempt to reposition 
issues message IEC613A to the 
attempt repositioning. If the 
tape positioning is to be attempted 
4 is set» indicating that OPEN rewind 



and attempt positioning. If the operator specifies 
that tape positioning is not to be reattempted^ control is 
returned to the calling module with a return code. 

When IFG0199I is given controls standard register linkage 
conventions are used for registers 1, 13» 1^» and 15. IFG0199E 
passes an open abend installation exit list (OAIXL)» in register 
If to the abend installation exit module. 



C^ 



The format of OAIXL follows^ 



Uord Boundary 



+0(00) 

+4(04) 

+8(08) 

+ 12(00 

+16(10) 

+20(14) 

+24(18) 

+28(1C) 



User Prot Key 



Option Flats 



Reserved 



Reserved 



Address of the protected copy of the DCB 



Address of the user's DCB Related to the abend 



Address of the UCB Related to the abend 



Address of the JFCB Related to the abend 



Address of the TIOT Related to the abend 



Abend code — Example X*6130000C* 



Installation work area (could be used as counter) 
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OPEN/EOV USER EXIT FOR NONSPECIFIC TAPE MOUNT REQUESTS 



This exit alloMS you to identify a specific tape volume to be 
requested in place of a nonspecific (scratch) volume. Only 
IBM-standard labeled tapes (SL) Mill be supported. The exit is 
invoked uihen open or EOV is to issue a mount request for a tape 
volume Mhere no volume serial number has been specified* and 
Mill get control before the mount message is issued. 



c 



^ 



0(00) Protection key of the user's DOB 
1(01) Option flags: 
Bits 

OAIXEXIT; used to determine Mhether the DCB 
abend user exit Mas taken 

On exit Mas taken 
Off exit Mas not taken 

1 OAIXREM; used to determine Mhether to reMind the 
tape volume 

On reMind the tape volume 

Off do not reMind the tape volume 

8 Address of the user's DCB related to the abend 
used to distinguish each unique exit parameter 
list 

28 4-byte Mork area used as a counter to determine 
the number of times tape positioning has been 
retried 

The installation exit returns to IFG0199E one of the folloMing 
return codes: 

Code Meaning 

0(00) Continue Mith the abend in process. 

4(04) If the OAIXREU flag is set* indicating to reMind the 

tape» reMind the tape volume; set the UCBFSCT and ,f"~% 

UCBFSEQ fields in the UCB to zero; and retry the abend (^ ) 
in process. 

If the OAIXREU flag is not set* indicating not to 
reMind the tape* retry the abend in process. 

For abend codes that the installation is allOMed to retry* see 
Data Management Services in the section that defines the abend 
codes that the user abend exit may retry. 

Modifying the IBM-Supplied Installation Exit Module: Because the 
IBM-supplied installation exit module only handles a particular 
abend situation* you may Mant to modify the source code of that 
module to perform corrective actions for other abend situations. 

You can obtain a copy of the source code from SYSl.SAMPLIB for 
modification using the editing facility that is available to 
you. After you have modified the source code* link-edit it into 
SYSl.LPALIB. The source program is Mritten in Assembler 
language* and uses only macros in SYSl.MACLIB. If you replace 
the supplied installation module* the exit module that you 
supply must have the entry point name IFG0199I and it must be 
reenterable. 



V-.> 
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The exit address must be in the DCB exit list. The exit list 
entry code used to identify this exit in the DCB exit list is 
X'17*. The exit is called in user key; the state Mill be the 
same state as uihen the open or EOV Mas issued; no locks Mill be 
held. 
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,0^ 









At entry to your exit routine* register contents are as follows* 
Register Contents 

Variable 

1 Address of the exit parameter list (in key 5? nonfetch 
protected storage) 

2-13 Contents before the macro instructions that gave 

Open/EOV control (OPEN, FEOV, EOV, PUT, and CHECK) 

14 Return address (must not be altered by the exit 
routine) 

15 Address of exit routine entry point 

The conventions for saving and restoring register contents ar& 
as folloMs: 

• The exit routine must preserve the contents of register 14. 
It need not preserve the contents of other registers. The 
operating system restores the contents of registers 2 
through 13 before returning control to your program. 

• The exit routine must not use the save area Mhose address is 
in register 13, because this area is used by the operating 
system. If the exit routine calls another routine or issues 
supervisor or data management macro instructions, it must 
provide the address of a neM save area in register 13. 

The exit parameter list contains the following! 

• Flags indicating SL tape, first entry to the exit, and 
whether called from open or EOV 

• The open option 

• Addresses of the DCB, volume serial number, and JFCB 

The high order bit of the last word in the list (the JFCB 
address) will be set to one. 

The format of the parameter list, which is mapped by macro 
lECOENTE, is shown in Figure 32 on page 134. 

The first time the exit is called (indicated by bit 7 of the 
first byte of the parameter list), the volume serial number 
field of the list contains a zero. 

The following return codes (in register 15) are allowed* 

Code Meaning 

0(00) Open/EOV will continue with the nonspecific mount 
request. 

4(04) Open/EOV will use the user-specified volume. Register 
contains the address of a 6-byte volume serial number. 
Open/EOV will request that the volume be mounted if the 
volume is not in use by this job or another job. 

If open or EOV finds the supplied volume serial number is in use 
by this job or another job (that is, the volume is enqueued), 
the exit is taken a subsequent time (indicated by bit 7 of the 
first byte of the parameter list). The address of the supplied 
volume serial number is passed in the parameter list to the 
exit. The return codes will be the same as the first entry of 
the exit. The exit will be entered repetitively until return 
code is passed back, or until return code 4 is passed back 
together with a volume serial number that is not in use. 
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Name 


Offset 


Bytes 


Description 


OENTklRDl 


00(00) 







Nonspecific tape request user exit 












parameter list 


OENTFLG 


00(00) 


1 




flags 


OENTOEOV 






0... 


• • • • 


called by open 


OENTOEOV 






1... 


• • « • 


called by EOV 








.XXX 


XXX. 


reserved 


OENTNTRY 






• ■ • • • 


...0 


first entry to exit 


OENTNTRY 






• • • • 


...1 


subsequent entry to exit 


OENTOPTN 


1 


(01) 


1 




open options 








xxxx 


« • • • 


reserved 








• • • « 


0000 


INPUT 








• • « • 


1111 


OUTPUT 








• • • • 


0011 


INOUT 








• • • • 


0111 


OUTIN 











0001 


RDBACK 




2 


(02) 


2 




reserved 


OENTDCBA 


4 


(04) 


4 




address of DCS 


OENTVSRA 


8 


(08) 


4 




zero or address of volume 
serial number 


OENTJFCB 


12 


(OC) 


4 




address of JFCB 


Figure 32. 


Format of 


Parameter List 


for Nonspecific Tape Mount User Ex 



( 






If the tape volume is not in use^ the exit Mill not be taken 
again even if some other reason (such as an I/O error » or 
invalid expiration date) causes the tape to be 'rejected. 

OPEN/EOV USER EXIT FOR IBM-STANDARD LABELED TAPE SECURITY VERIFICATION 

This exit alloMS authorized programs to verify that an 
IBM-standard labeled tape selected by open or EOV should^ in 
fact# be used# and whether certain security checks may be 
bypassed. The exit supports only IBM-standard labeled tape 
(SL)» and is taken only for APF authorized programs for uihich 
the program property "bypass password (and RACF) checking" is 
active for (for information on program properties* see System 
Programming library* Job Management ) . 






The exit address must be in the 
entry code used to identify the 



DOB exit list, 
exit is X»18». 



The exit list 



The exit is taken from open and EOV after volume verification 
and positioning* and before password dnd/or expiration date 
checking. The exit is called in user key; the state will be the 
same state as when the open or EOV was issued; no locks will be 
held. 

At entry to your exit routine* register contents &rB as follows: 

Register Contents 

Variable 

1 Address of the exit parameter list (in key 5* nonfetch 
protected storage) 

2-13 Contents before the macro instruction that gave 

Open/EOV control (OPEN, FEOV, EOV, PUT, CHECK, and 
GET) 

14 Return address (must not be altered by the exit 
routine) 

15 Address of exit routine entry point 



134 MVS/370 System Programming Library: Data Management 



The conventions for saving and restoring register contents are 
as folloMs: 

• The exit routine must preserve the contents of register 14. 
It need not preserve the contents of other registers. The 
operating system restores the contents of registers 2 
through 13 before returning control to your program. 

• The exit routine must not use the save area Mhose address is 
in register 13* because this area is used by the operating 
system. If the exit routine calls another routine or issues 
supervisor or data management macro i nstructi ons> it must 
provide the address of a new save area in register 13. 

The exit parameter list contains the following* 

• Flags indicating whether the exit was called from open or 
EOV» and whether the first data set on the volume is to be 
written 

• The open option 

• Addresses of the DCB> volume serial number* tape label* and 
JFCB 

The tape label is either the HDRl label of a data set to be read 
forward or overwritten, the EOFl label of a data set to be read 
backward* or the EOFl label of a data set after which the new 
data set is to written. The high order bit of the last word in 
the parameter list (the JFCB address) is set to one. 

The format of the parameter list* which is mapped by macro 
lECOEVSE* is shown in Figure 33. 






Description 

SL tape security verification user 

exit parameter list 
flags 

called by open 
called by EOV 
reserved 
first data set to be written 

on volume* or data set being read 
second or subsequent data set 

to be written on volume 
open options 
reserved 
INPUT 
OUTPUT 
INOUT 
OUTIN 
RDBACK 
reserved 
address of DCB 

address of volume serial number 
address of tape label (HDRl or 

EOFl) 

address of JFCB 



List for IBM-Standard Labeled Tape Security 
Verification User Exit 



Name 


Offset 


Bytes 


OEVSWRDl 


00(00) 







OEVSFLG 

OEVSOEOV 

OEVSOEOV 


00(00) 


1 

0... 

1... 





OEVSFILE 




.XXX 

• • • • 


XXX. 

...0 


OEVSFILE 




• • • • 


...1 


OEVSOPTN 


01(01) 


1 




OEVSDCBA 
OEVSVSRA 
OEVSHDRl 


02(02) 
04(04) 
08(08) 
12(0C) 


xxxx 

z" 

4 
4 
4 


OOOO 
1111 
0011 
0111 
0001 


OEVSJFCB 


16(10) 


4 




Figure 33. 


Format of 


Parameter L 
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The folloMing return codes (in register 15) aro allouecf: 

Code Meaning 

0(00) Use the volume as if the exit Mas not entered. 

4(04) Output processing ? reject the volume and request that a 
scratch tape be mounted (this Mill cause the open/EOV 
user exit for nonspecific tape volume mount requests to 
get control if that exit is defined). If the data set 
sequence number to be Mritten is not 1» treat as return 
code 8. 

Input processing ? treat as return code 8. 

Note: It is the user's responsibility to determine 
Mhether a data set open for INOUT or OUTIN is being 
processed for output or input at the time the exit is 
given control from EOV. Bit DCBOFLWR in field DCBOFLGS 
is set to 1 if the EOV is being processed for output. 

8(08) Abnormally terminate the open or EOV» using the 

completion codes 913-34 for open and 937-29 for EOV. 

12(0C) Use the volume; the passMord or expiration date of the 
tape label Mill not prevent the existing data set from 
being overMritten. 

16(10) Use the volume. The passNord» expiration date of the 

tape label » or unlike data set names should not prevent 

the first data set on a volume from being Mritten; 

hoNever» in order to Mrite other than the first data 

set» the data set must have the same security 

protection as the data set after Mhich it Mill be 

Mritten. ^> 



w 
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CHAPTER 7. SYSTEM MACRO INSTRUCTIONS 



This chapter describes miscellaneous macro instructions that 
alloM you to> 

• Modify control blocks 

• Obtain information from control blocks and system tables 

• Perform track capacity calculations 

• Allocate a data set based on a partial DSCB 

Before reading this chapter* you should be familiar with the 
follouiing publications* 

• OS/VS-DOS/VSE-VM/370 Assembler language contains the 
information necessary to code programs in the assembler 
language. 

• Debugging Handbook contains format and field descriptions of 
the data areas referred to in this chapter. 



INTRODUCTION 






The system macro instructions are described in these functional 
groupings! 

Mapping (lEFUGBOB, lEFJFCBN, and CVT) 

Obtaining device characteristics (DEVTYPE) 

Manipulating the JFCB (RDJFCB) 

Data security (DEBCHK) 

Manipulating queues (PURGE and RESTORE) 

Performing track capacity calculations (TRKCALC) 

Allocating a data set based on a partial DSCB (REALLOC) 



MAPPING SYSTEM DATA AREAS 



The IEFUCBOB» lEFJFCBN, and CVT macro instructions are used as 
DSECT expansions that define the symbolic names of fields within 
the unit control block (UCB)» job file control block (JFCB)> and 
communication vector table (CVT)» respectively. 

The CVT» lEFUCBOB* and lEFJFCBN macro definitions are in a 
distribution library named SYSl . AMODGEN. Before you can issue 
the macros, you must copy them from SYSl. AMODGEN into 
SYSl.MACLIB (the lEBCOPY utility can be used to copy the 
macros), or SYSl. AMODGEN may be concatenated to the macro 
library before reference is made to SYSl. AMODGEN. 

The fields in these blocks are shown and described in Debugging 
Handbook. 



lEFUCBOB — MAPPING THE UCB 



This macro instruction defines the symbolic names of the fields 
in the unit control block (UCB). The macro does not include a 
DSECT statement. However, if you specify PREFIX=YES, the DSECT 
statement is provided. 
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The format is: 



C«5ymb9lJ 


ZEFUCBOB 


CLZST=CNO|YES}] 
C,PREFIX=CNO|YES}] 



LIST=CNO|YES} 
NO 



YES 



specifies that only the UCB prolog is to be printed. 



specifies that the UCB prolog and the rest of the UCB 
are to be printed. 



PREFIX=:CNO|YES} 
NO 



YES 



specifies that no prefix is to be printed. 



specifies that the prefix and main body of the UCB are 
to be printed. A DSECT statement is included if you 
specify PREFIX=YES. 



ZEFJFCBN — NAPPING THE J FOB 



This macro instruction defines the symbolic names of the fields 
in the job file control block (JFCB). The macro does not 
include a DSECT statement. If you require one* code a DSECT 
statement before the macro statement. 

The format is? 



[symbol J 


ZEFJFCBN 


[LZST=CNO|YES}] 






tZST=CNO|YES} 
NO 



YES 



specifies that only the JFCB prolog is to be printed. 



specifies that the JFCB prolog and the rest of the 
JFCB are to be printed. 



CVT— MAPPZNG THE CVT 



This macro instruction defines the symbolic names of all fields 
in the communication vector table (CVT). 

The format is? 



I symbol 1 


CVT 


[DSECT=CNO YES}] 
C,LZST=CNO YES}] 



DSECT=CNO|YES} 
NO 



YES 



specifies that you do not uant a DSECT 



specifies that you want a DSECT. 
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LZST=CNOlYES} 
NO 



YES 



specifies that only the CVT prolog is to be printed. 



specifies that the CVT prolog and the rest of the CVT 
are to be printed. 



OBTAINING I/O DEVICE CHARACTERISTICS 



Use the DEVTYPE macro instruction to request information 
relating to the characteristics of an I/O device* and to cause 
this information to be placed into a specified area. (The 
results of a DEVTYPE macro instruction executed before a 
checkpoint is taken should not be considered valid after a 
checkpoint/restart occurs.) The IHADVA macro maps the data 
returned by the DEVTYPE macro. 

The topics that follow discuss the DEVTYPE macro* device 
characteristics* and particular output for particular devices. 



DEVTYPE MACRO SPECIFICATION 

The format is* 



[svmbol] 


DEVTYPE 


ddloc-addrx 
»area-addrx 
[,DEVTAB] 
[,RPS] 



o 



ddloc-addrx 

the name of an 8-byte field that contains the symbolic name 
of the DD statement to which the device is assigned. The 
name must be left justified in the 8-byte field* and must 
be folloMed by blanks if the name is less than eight 
characters. The doubleMord need not be on a doubleMord 
boundary. 

area-addrx 

the name of an area into which the device information i s to 
be placed. The area can be two* five* or six fullwords* 
depending on whether or not the DEVTAB and RPS operands are 
specified. The area must be on a fullword boundary. 

DEVTAB 

This operand is only required for direct access devices. 
If DEVTAB is specified* the following number of words of 
information is placed in your area: 

• For direct access devices^ 5 words 

• For nondi rect access devices: 2 words 

If you do not code DEVTAB* one word of information is 
placed in your area if the reference i s to a graphics or 
teleprocessing device* for any other type of device* two 
words of information are placed in your area. 



RPS 



If RPS is specified* DEVTAB must also be specified. The 
RPS parameter causes one additional full word of RPS 
information to be included with the DEVTAB information. 






Note: Any reference for a DUMMY data set in the DEVTYPE macro 
instruction will cause eight bytes of zeros to be placed in the 
output area. Any reference to a SYSIN or SYSOUT data set causes 
X*00000102' to be placed in word and 32*760 (X'00007FF8* ) to 
be placed in word 1 in the output area. Any reference to a file 
allocated to a TSO terminal causes X'OOOOOlOl* to be placed in 
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Mord and 32,760 (X'00007FF8* ) to be placed in Mord 1 in the 
output area. 



DEVICE CHARACTERISTICS INFORMATION 



Mord 4 



Byte Block overhead, block without key — the number 
of bytes to be subtracted from word 3, bytes 2 
or 3 or bytes 2 and 3, if a block is not keyed. 

If bit 3, byte 1 of word 4 is 1, this byte 
contains the modulo factor for a modulo device. 



1 






The following information is placed into your area as a result 
of issuing a DEVTYPE macro- 

Mord 

Describes the device as defined in the UCBTYP field of the 
UCB. For a complete description of this field, refer to 
Debugging Handbook . 

Mord 1 

Maximum block size. For direct access devices, this value 
is the smaller of either the maximum size of an unkeyed 
block or the maximum block size allowed by the operating 
system; for magnetic or paper tape devices, this value is 
the maximum block size allowed by the operating system. 
For all other devices, this value is the maximum block size 
accepted by the device. 

If DEVTAB is specified, the next three fullwords contain the 
following inform*ation about direct access devices* 

Mord 2 

Bytes 0-1 The number of physical cylinders on the device, 
excluding alternates. 

Bytes 2-3 The number of tracks per cylinder. 

Mord 3 

Bytes 0-1 Maximum track length. Note that for the 2305, 
3330/3333 Model 1 or 11, 3340/334<i, 3350, 3375, 
and 3380 direct access devices, this value is ^*i^ 
not equal to the value in word 1 (maximum block 
size) as it is for other IBM direct access 
devices. 

Note* Before using bytes 2 and 3, please read the description of 
word \. 

Byte 2 Block overhead, keyed block — the number of 

bytes required for gaps and check bits for each 
keyed block other than the last block on a 
track. 

Byte 3 Block overhead — the number of bytes required 

for gaps and check bits for a keyed block that 
is the last block on a track. 

Bytes 2-3 Block overhead — the number of bytes required 

for gaps and check bits for any keyed block on 
a track including the last block. Use of this 
form is indicated by a one in bit ^, byte 1 of 
word 4. 

Basic overhead — the number of bytes required 
for the count field. Use of this form is 
indicated by a one in bit 3, byte 1 of word 4. 



,/f ^\ 
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Byte 1 

Bit If on» the number of cylinders» as 
indicated in Mord Z, bytes 0-1 are 
invalid. This bit Mill be on only 
for 3340 devices. 

Bits 1-2 Reserved. 

Bit 3 If on» indicates a modulo device 
(3375» 3380). To calculate the 
number of data bytes required for a 
data block for a modulo device^ see 
the device data in Data Management 
Services . 

Bit 4 If on> bytes 2 and 3 of word 3 

contain a halfMord giving the block 
overhead for any block on a track* 
including the last block. 

Bits 5-6 Reserved. 

Bit 7 If on» a tolerance factor must be 
applied to all blocks except the 
last block on the track. 

Bytes 2-3 Tolerance factor — this factor is used to 

calculate the effective length of a block. The 
calculation should be performed as folloMS^ 

Step 1 add the block's key length to the 
block's data length. 

Step 2 test bit 7 of byte 1 of word 4. If 
bit 7 is 0, perform step 3. If bit 
7 is 1> multiply the sum computed 
in step 1 by the tolerance factor. 
Shift the result of the 
multiplication nine bits to the 
right. 

Step 3 add the appropriate block overhead 
to the value obtained above. 

If bit 3, byte 1 of word 4 is 1, bytes (2-3) 
contain the overhead for the data or key field. 

If DEVTAB and RPS are specified* the next fullword contains 
the following information^ 

Mord 5 

Bytes 0-1 RO overhead for sector calculations 

Byte 2 Number of sectors for the device 

Byte 3 Number of data sectors for the device 

Figure 34 on page 142 shows the output for each device type that 
results from issuing the DEVTYPE macro. 

Control is returned to your program at the next executable 
instruction following the DEVTYPE macro instruction. If the 
information concerning the ddname you specified has been 
successfully moved to your work area* register 15 will contain 
zeros. Otherwise* register 15 will contain X*04*> indicating 
that the ddname was not found. 
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Device^»2 


Haxinnjin 
Record Size 
(Uord If in 
Decimal) 


DEVTAB (Uords 2> 3* and 
4f in Hexadecimal) 


RPS (Uord 5» 

In 

Hexadecimal) 


2540 Reader 


80 


Not Applicable 


Not Applicable 


2540 Reader w/CI 


80 


Not Applicable 


Not Applicable 


2540 Punch 


80 


Not Applicable 


Not Applicable 


2540 Punch w/CI 


80 


Not Applicable 


Not Applicable 


2501 Reader 


80 


Not Applicable 


Not Applicable 


2501 Reader m/CI 


80 


Not Applicable 


Not Applicable 


2520 Reader-Punch 


80 


Not Applicable 


Not Applicable 


2520 Reader-Punch 
w/CI 


80 


Not Applicable 


Not Applicable 


1287 Optical Reader 


80 


Not Applicable 


Not Applicable 


128S Optical Reader 


80 


Not Applicable 


Not Applicable 


3886 Optical Reader 


80 


Not Applicable 


Not Applicable 


3890 Document 
Processor 


80 


Not Applicable 


Not Applicable 


1419/1275 
Reader/Sorter 


80 


Not Applicable 


Not Applicable 


3505 Reader 


80 


Not Applicable 


Not Applicable 


3505 Reader w/CI 


80 


Not Applicable 


Not Applicable 


3525 Punch 


80 


Not Applicable 


Not Applicable 


3525 Punch w/CI 


80 


Not Applicable 


Not Applicable 


1403 Printer 


120' 


Not Applicable 


Not Applicable 


1403 w/UCS 


120' 


Not Applicable 


Not Applicable 


1443 Printer 


120* 


Not Applicable 


Not Applicable 


3203 Model 5 Printer 


132 


Not Applicable 


Not Applicable 


3211 Printer 


132' 


Not Applicable 


Not Applicable 


3800 Printing 
Subsystem 


136* 


Not Applicable 


Not Applicable 


4245 Printer 


132 


Not Applicable 


Not Applicable 


2671 Paper Tape 
Reader 


32760 


Not Applicable 


Not Applicable 


1052 

Pr i nter-Keyboard 


130 


Not Applicable 


Not Applicable 


1053 Printer 




Not Applicable 


Not Applicable 


3210 
Printer-Keyboard 


130 


Not Applicable 


Not Applicable 



Figure 34 (Part 1 of 2). Output Obtained from Issuing DEVTYPE Macro 



c 
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Devicei»2 


Maximum 
Record Size 
(Mord 1» in 
Decimal) 


DEVTAB (Uords Z, 3, and 
4» in Hexadecimal) 


RPS (Mord S, 

in 

Hexadecimal) 


3215 

Pri nter-Keyboard 


130 


Not Applicable 


Not Applicable 


3895 Reader 
Inscriber 


74 


Not Applicable 


Not Applicable 


2400 (9-track) 


32760 


Not Applicable 


Not Applicable 


2400 (9-track, p.e.) 


32760 


Not Applicable 


Not Applicable 


2400 (9-track, d.d.) 


32760 


Not Applicable 


Not Applicable 


2400 (7-track) 


32760 


Not Applicable 


Not Applicable 


2400 (7-track, d.c.) 


32760 


Not Applicable 


Not Applicable 


2495 Tape Cartridge 
Reader 





Not Applicable 


Not Applicable 


3400 (9-track, p.e.) 


32760 


Not Applicable 


Not Applicable 


3400 (9-track, d.d.) 


32760 


Not Applicable 


Not Applicable 


3400 (7~track) 


32760 


Not Applicable 


Not Applicable 


2314/2319 DAS 
Faci li ty 


7294 


00CB00141C7E922D2D010216 


Not Applicable 


2305 Model 1 
Fixed-Head Storage 


14136 


0030000838E8027ACA080200 


02985A57 


2305 Model 2 
Fixed-Head Storage 


14660 


006000083A0A01215B080200 


0140B4B1 


3330/3333 Disk 
Storage 


13030 


019B0013336DBFBF38000200 


00ED807C 


3330V MSS Virtual 
Volume 


13030 


019B0013336DBFBF38000200 


00ED807C 


3330 Model 11 (or 
3333 Model 11) Disk 
Storage 


13030 


032F0013336DBFBF38000200 


00ED807C 


3340 Disk Storage 
(35 megabytes) 


8368 


015D000C2157F2F24B000200 


0125403D 


3340/3344 Disk 
Storage (70 
megabytes) 


8368 


0230001E4B36010B52080200 


0125403D 


3350 Disk Storage 


19069 


0230001E4B36010B52080200 


0185807B 


3375 Disk Storage 


32760 


O3BFOO0C8CAO00EO2O10O0BF 


0340C4BB 


3380 Disk Storage 


32760 


0376000FBB6001002010010B 


04E0DED6 


2250 Model 1 Display 
Unit 




Not Applicable 


Not Applicable 


2250 Model 3 Display 
Unit 




Not Applicable 


Not Applicable 



Figure 34 (Part 2 of 2). Output Obtained from Issuing DEVTYPE Macro 

Notes to Figure 34: 
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CI — card image feature; d.c. — data conversion; d.d. — dual 
density; p.e. — phase encoding; UCS — universal character set; 
w/ — with. 

Device codes are presented in System Programming Library* 
Debugging Handbook . 

Although certain models can have a larger line size* the 
minimum line size is assumed. 

The IBM 3800 Printing Subsystem can print 136 characters per 
line at 10-pitch, 163 characters per line at 12-pitch» and 
20^ characters per line at 15-pitch. The machine default is 
136 characters per line at 10-pitch. 



Communication Equipment 


Record Size 


1030>1050,83B3, 
TWX, 2250,5360 


Not Applicable 


1060, 115A, 1130 


Not Applicable 


2780 


Not Applicable 


27<fO 


Not Applicable 



READING AND MODIFYING A JOB FILE CONTROL BLOCK 



To accomplish the functions that are performed as a result of an 
OPEN macro instruction, the open routine requires access to 
information that you have supplied in a data definition (DD) 
statement. This information is stored by the system in a job 
file control block (JFCB). 

In certain applications, you may find it necessary to modify the 
contents of a JFCB before issuing an OPEN macro instruction. 
For example, suppose you are adding records to the end of a 
sequential data set. You might Nant to add a secondary 
allocation quantity to alloM the existing data set to be 
extended when the space currently allocated is exhausted. To 
assist you, the system provides the RDJFCB macro instruction. 
This macro instruction causes a specified JFCB to be moved from 
the SWA (scheduler work area), where it is stored, to an area 
specified in an exit list. (The use of the RDJFCB macro 
instruction with an exit list is shown under "RDJFCB — Read a Job 
File Control Block" on page 148. The symbolic names and field 
descriptions of the JFCB are contained in Debugging Handbook . ) 
When you subsequently issue the OPEN macro instruction, you must 
indicate, by specifying the TYPE=J operand, that you want to 
open the data set using the JFCB in the area you specified. 

At the conclusion of open processing, the JFCB is moved back to 
the SWA, unless you set the bit JFCNWRIT in the field JFCBTSDM 
to one before you issue the OPEN macro instruction. 



\^^ 



caution: if the JFCB, 
set, is not available 
errors may occur. 



which the system used to open the data 
in SWA during EOV or CLOSE processing. 
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C; 









Some of the modifications that are commonly made to the JFCB 
include: 

• Moving the creation and expiration date fields of the DSCB 
into the JFCB (see "Using RDJFCB for MSS Virtual Volumes" 
beloM) . 

• Moving the secondary allocation quantity from the DSCB into 
the JFCB (see "Using RDJFCB for MSS Virtual Volumes" beloui). 

• Moving the DCB fields from the DSCB into the JFCB. 

• Adding volume serial numbers to the JFCB (see "Using RDJFCB 
for MSS Virtual Volumes" and "RDJFCB Security" beloM). 

Volume serial numbers in excess of five are written to the 
JFCBX (extension) located in the SUA. The JFCBX cannot be 
modified by user programs. 

• Modifying the data set sequence number field in the JFCB. 

• Modifying the number-of-volumes field in the JFCB (see 
"Using RDJFCB for MSS Virtual Volumes" beloM). 

• Setting bit JFCDQDSP in field JFCBFLG3 to invoke the tape 
volume DEQ at demount facility (see "DEQ at Demount Facility 
for Tape Volumes^" beloM). 

USING RDJFCB FOR MSS VIRTUAL VOLUMES: Care must be taken in 
using RDJFCB if the data set resides on MSS virtual volumes such 
that-. 

• The expiration date added does not conflict with other 
volumes within the specified MSVGP. 

• The secondary allocation quantity should be in cylinder 
increments and be a multiple or sub-multiple of the primary 
allocation quantity to avoid fragmentation. 

• The number of volumes must not exceed the number available 
in the specified MSVGP. 

• Any volume serial numbers added to the JFCB should exist in 
the MSVGP. 

RDJFCB SECURITY: The volume serial numbers specified in the 
user-supplied JFCB will be compared with the volume serial 
numbers in the system JFCB located in the SUA. Each different 
volume serial number will be enqueued exclusively. The volumes 
Mill stay enqueued until the job step terminates since the close 
routines Mill not dequeue the volumes. If the job step already 
has the volume open» OPEN TYPE=J Mill continue. If the volume 
is enqueued by another job step» a 413 abend will occur with a 
return code of 04. 

Some JFCB modifications can compromise the security of existing 
password-protected data sets. The folloMing modifications are 
specifically not alloMed* unless the program making the 
modifications is authorized or can supply the passMord: 

• Changing the disposition of a passMord-protected data set 
from OLD or MOD to NEU. 

• Changing the data set name of one or more of the volume 
serial numbers Nhen the disposition is NEU. 

• Changing the label processing specifications to bypass label 
processing. 

Note: An authorized program is one that is either in supervisor 
state» executing in one of the system protection keys (keys 
through 7)> or authorized under the Authorized Program Facility. 
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RDJFCB USE BY AUTHORIZED PROGRAMS: If you change the data set 
name in the JFCB» you should do a system enqueue on the major 
name of **SYSDSN" for the substituted data set name. To use the 
correct interface with other system functions (for example* 
partial release)/ the ENQUEUE macro should include the TCB of 
the initiator and the length of the data set name (with no 
trailing blanks). Mhen you complete processing of the data set* 
you should use the DEQ macro to release the resources. 

If you rewrite the JFCB» you must set bit zero at JFCBNASK * 4 
to one. 



DEQ AT DEMOUNT FACILITY FOR TAPE VOLUMES 



This facility is intended to be used by long-running programs 
which create an indefinitely long-running tape data set (such as 
a log tape). Use of this facility by such a program permits the 
processed volumes to be allocated to another job for processing 
(such as data reduction). This processing is otherwise 
prohibited unless the indefinitely long data set is closed and 
dynamically unallocated. 

You may invoke this facility only through the RDJFCB/OPEN TYPE=J 
interface by setting bit JFCDQDSP (bit 0) in field JFCBFLG3 
(offset 163 or X'AS*) to 1. The volume serial of the tape is 
dequeued when the volume is demounted by OPEN or EOV with 
message IEC502E when all of the following conditions are 
present: 

• The tape volume is verified for use by OPEN or EOV. 

• JFCDQDSP is set to 1. 

• The program is APF authorized (protect key and 
supervisor/problem state are not relevant). 

• The tape volume is to be immediately processed for output. 
That is* either OPEN verifies the volume and the OPEN option 
is OUTPUT, OUTIN, or OUTINX; or EOV verifies the volume and 
the DCB is opened for OUTPUT, OUTIN, INOUT, or EXTEND, and 
the last oper.ation against the data set was an output 
operation (DCBOFLMR is set to 1). 

Note that in order for EOV to find JFCDQDSP set to 1, the 
program must not inhibit the rewrite of the JFCB by setting bit 
4 of JFCBTSDM to 1. 

The tape volume is considered verified after file protect, label 
type, and density conflicts have been resolved. The volume is 
dequeued when demounted after this verification, even if further 
in OPEN or EOV processing the volume is rejected because of 
expiration date, security protection, checkpoint data set 
protection, or an I/O error. 

Mhen the volume serial is dequeued, the volume becomes available 
for allocation to another job. However, because the volume DEQ 
is performed without unallocating the volume, care must be 
exercised both by the authorized program and the installation to 
prevent misuse of the DEQ at demount facility. A discussion of 
such misuse follows. 

1. The authorized program must not close and reopen the data 
set using the tape volume DEQ at demount facility. If it 
does, one of the following can occur: 

a. The dequeued volume may be mounted and in use by another 
job. Uhen the volume is requested for mounting, for the 
authorized program, the operator is unable to satisfy 
the mount. Therefore, the operator must either cancel 
the requesting job, cancel the job using the volume, 
wait for the requesting job to time out, or wait for the 
job using the volume to terminate. 






jT^., 
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b. The dequeued volume may be allocated to another job but 
not yet in use. The operator mounts the volume to 
satisfy the mount request of the authorized job. Uhen 
the volume is requested for mounting by the other job» 
the operator is unable to satisfy the mount requests and 
is faced Mith the same choices as in a» above. 

c. The dequeued volume may not yet be allocated to another 
job and the volume is mounted to satisfy the mount 
request of the authorized job. Another job may allocate 
the volume and when the volume is requested for 
mounting* the situation is the same as in br above. 

It is the responsibility of the installation that permits a 
program to run with APF authorization to ensure that it does 
not close and reopen a data set using the DEQ at demount 
faci li ty. 

• 

2. Care should be exercised when an authorized program uses the 
DEQ at demount facility (data set 1) but processes another 
tape data set (data set 2). Assume the same volume serial 
numbers have been coded in the DD statements for data set 1 
and data set 2. As the volumes of data set 1 are demounted* 
they are dequeued even though those volumes may yet be 
requested for data set 2. All of the problems explained in 
a* b> and c in 1 above* may occur as data set 2 and another 
job contend for a dequeued volume. 

This problem should not occur* given the intended use of the 
DEQ at demount facility. That is* a long-running 
application creating an indefinitely long tape data set. 
This type of application is not normally invoked through 
batch execution Mith user-uiritten DD statements. 

3. Once a volume has been demounted and dequeued because of the 
DEQ at demount facility* the volume is not automatically 
rejected by the control program Mhen mounted in response to 
a specific or nonspecific mount request. Without the use of 
the facility* the control program can recognize (by the ENQ) 
that the volume is in use* and reject the volume. 
Therefore* operations procedures* in effect to prevent 
incorrect volumes from being mounted* should be reviewed in 
the light of reduced control program protection from such 
errors when the DEQ at demount facility is used. 
Specifically* if a volume is remounted for an authorized 
program and the volume had been used previously by that 
authorized program* duplicate volume serial numbers will 
exist in the JFCB and the control program will be unable to 
release the volume during EOV processing. 

4. Checkpoint/restart considerations are discussed in 
Checkpoint/Restart . 



OPEN — INZTIALZZE DATA CONTROL BLOCK FOR PROCESSING THE JFCB 



The OPEN macro instruction initializes one or more data control 
blocks so that their associated data sets can be processed. 

A full explanation of the operands of the OPEN macro 
instruction* except for the TYPE=J option* is contained in Data 
Management Macro Instructions . The TYPE=J option* because it is 
used in conjunction with modifying a JFCB* should be used only 
by the system programmer or only under the system programmer's 
supervision. 
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[symbol] 


OPEN 


Cdcb-addr> [(options)]* . . . ) 
I,TYPE=J1 






1^ 



TYPE=J 

specifies that for each data control block referred 
have supplied a job file control block (JFCB) to be 
during initialization. A JFCB is an internal 
representation of information in a DD statement. 



to* you 
used 



During initialization of a data control block, its 
associated JFCB may be modified Mith information from the 
data control block or an existing data set label or with 
system control information. 

The system always creates a job file control block for each 
DD control statement. The job file control block is placed 
in the SUA (scheduler Mork area). Its position* in 
relation to other JFCBs created for the same job step» is 
noted in a table in virtual storage. 



Uhen this operand is specified* 
statement. However* the amount 
DD statement i s at your discret 
many fields of the system-creat 
If you specify DUMMY on your DD 
will ignore the JFCB DSNAME and 
(See the examples of the RDJFCB 
coding example that modifies a 



you must also supply a DD 
of information given in the 
ion because you can modify 
ed job file control block, 
statement, the open routine 
open the data set as dummy, 
macro instruction for a 
system-created JFCB.) 



Note: The DD statement must specify at least: 

• Device allocation (refer to JCL for methods of preventing 
share status) 

• A ddname corresponding to the associated data control block 
DCBDDNAM field 



/^" 



'"i.^*^ 



RDJFCB — READ A JOB FILE CONTROL BLOCK 



The RDJFCB macro instruction causes a job file control block 
(JFCB) to be moved from the SUA (scheduler work area) into an 
area of your choice as identified via the EXIST parameter of 
RDJFCB for each data control block specified. 



[symbol] 


RDJFCB 


(dcb-address 

* [ (options J] > . . . ) 



dcb-address, (opti ons) 

(same as the dcbaddress, optionl, and optionZ operands of 
the OPEN macro instruction, as shown in Data Management 
Macro Instructions ) . 

Although the option operands ^r^ not meaningful during the 
execution of the RDJFCB macro instruction, these operands 
can appear in the list form of either the RDJFCB or OPEN 
macro instruction to generate identical parameter lists, 
which can be referred to with the execute form of either 
macro instruction. 
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Examples: In Figure 35 on page 1^9» the macro instruction at EXl 
creates a parameter list for tuo data control blocks* INVEN and 
MASTER. In creating the list* both data control blocks are 
assumed to be opened for input; option2 for both blocks is 
assumed to be DISP. The macro instruction at EX2 reads the 
system-created JFCBs for INVEN and MASTER from the SUA into the 
area you specified^ thus making the JFCBs available to your 
problem program for modification. The macro instruction at EX3 
modifies the parameter list entry for the data control block 
named INVEN and indicates* through the TYPE-J operand* that the 
problem program is supplying the JFCBs for system use. 



fy 



c 
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M W\^ 



/ 






EXl 



RDJFCB (INVEN,, MASTER), MF=L 



EX2 



EX3 



LSTB 



INVEN 


DCB 


MASTER 


DCB 


LSTA 


DS 




DC 




DC 



JFCBAREA DS 



RDJFCB MF=CE,EX1) 



OPEN CCRDBACK, LEAVE) ),TYPE=J,MF=(E, EXl) 



EXLST=LSTA,.. 

EXLST=LSTB,,. 

OF 

X'07' 

AL3(JFCBAREA) 



0F,176C 



OF 



DS 



Figure 35. Sample Code Using RDJFCB Macro 






Multiple data control block addresses and associated options may 
be specified in the RDJFCB macro instruction. This facility 
makes it possible to read several job file control blocks in 
parallel . 

An exit list address must be prrovided in each data control block 
specified by an RDJFCB macro instruction. Each exit list must 
contain an active entry that specifies the virtual storage 
address of the area into Mhich a JFCB is to be placed. A full 
discussion of the exit list and its use is contained in Data 
Management Service!^ . The format of the job file control block 
exit list entry is as follows: 



Types of 


Hexadecimal 


Contents of Exit List Entry 


Exit List 


Code 


(LoM-order Bytes) 


Entry 


(High-Order 
Byte) 




Job file 


07 


Address of a 176-byte area to 


control 




be provided if the RDJFCB or 


block 




OPEN (TYPE=J) macro 
instruction is used. This 
area must begin on a fullNord 
boundary and must be located 
Mithin the user's region. 



The virtual storage area into which the JFCB is read must be at 
least 176 bytes long. 

The data control block may be open or closed when this macro 
instruction is executed. 

If the JFCB is read successfully for all DCBs in the parameter 
list, a return code of zero is placed in register 15. If the 
JFCB is not read for any of the DCBs because the DDNAME is 
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blank* or a DD statement is not provided» a return code of 4 i s 
placed in register 15. 

naming* The following errors cause the results indicated^ 



Error 


Result 


A DD statement has not been 
provided. 


A return code of ^ i s 
placed in register 15. 


DDNAME field in DCB is 
blank. 


A write-to-programmer is 
issued* the request for 
this DCB is ignored* and a 
return code of 4 i s placed 
in register 15. 


A virtual storage address 
has not been provided. 


Abnormal termination of 
task. 



Note that if you want to open a VTOC data set to change its 
contents (that is* open it for OUTPOI* OUYIH* iNOUl* UPDAT* 
OUTINX* or EXTEND)* your program must be authorized under the 
Authorized Program Facility (APF). APF provides security and 
integrity for your data sets and programs. Details on how you 
authorize your program are provided in System Programming 
Library* Supervisor Services and Macro Instructions . 

If the RDJFCB routine fails while processing a DCB associated 
with your RDJFCB request* yeur task is abnormally terminated. 
None of the options available through the DCB ABEND exit* cs 
described in Data Management Services * is available when a 
RDJFCB macro instruction is issued. 



Mhen using concatenated data 
modify only the first JFCB. 



sets* the RDJFCB routine will 



,^"^" 



Vy 



ENSURING DATA SECURITY BY VALIDATING THE DATA EXTENT BLOCK 



Protecting one user's data from inadvertent or malicious access 
by an unauthorized user depends on protection of the data extent 
block (DEB). The DEB is a critical control block because it 
contains information about the device a data set is mounted on* 
and describes the location of data sets on direct access device 
storage volumes. The DEB also contains the address of the 
appendage vector table (AVT). Using the AVT* an unauthorized 
user can modify the AVT to give control to a routine in 
supervisor state to read from and write to data sets to which 
access would otherwise be denied. 

To guarantee protection of the DEB* the DEBCHK macro instruction 

is provided. The DEBCHK macro instruction can be found in 

SYSl.MACLIB. The DEBCHK macro is issued by several components 

of the system control program. For example? 

• The open access method executors issue the macro to add the 
address of a DEB they have built to a list of valid 
addresses called the DEB table. The DEB validity checking 
routine builds and maintains a DEB table for each job step. 

• The EXCP Processor uses the macro to verify that the DEB 
passed with each EXCP request is in the DEB table. 

• The close component issues the macro to remove a DEB from 
the DEB table. 

If you code a routine that builds a DEB* you must add the 
address of the DEB you built to the DEB table. If you code a 
routine that depends on the validity of a DEB that is passed to 
your routine* you should verify that the DEB passed to your 
routine has a valid entry in the DEB table and points to your 
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DCB or access method control block (ACB). Use the TYPE=ADD and 
the TYPE=VERIFY operands of the macro* respectively. 

To prevent an asynchronous routine from changing or deleting* or 
assigning a neui DEB to a DCB» you must hold the local lock. In 
this case* you must use the branch entry to the DEBCHK verify 
routine. 

Additional details about the functions provided by the DEB 
validity checking routine and about the contents of the DEB 
table are available in Qpen/Close/EOV Lcaic . 

The DEBCHK macro instruction provides four functions^ 

• Adds the address of a DEB to the DEB table* uihich is located 
in protected storage. The DEB table contains the address of 
every user DEB associated Mith a given job step. Every 
system control program component that builds a user DEB must 
add the address of that DEB to a DEB table. 

• Verifies that the DEB table associated Nith a given job step 
contains the address of a valid DEB and that the DEB points 
to the DCB (or ACB). Any system control program component 
or problem program can use this function to verify that a 
DEB is valid. 

• Deletes the address of a DEB from the DEB table. Any 
program that deletes a user DEB must* before it deletes the 
DEB, issue a DEBCHK macro with a TYPE=DELETE operand to 
delete the address of the DEB from the DEB table. If the 
DEB validity checking routine encounters an error Mhile 
deleting the address from the DEB table* the job step is 
abnormally terminated. 

• Deletes the address of a DEB from the DEB table in the same 
May as the preceding function* except that* instead of 
terminating the job step> this function merely returns an 
error code in register 15. This function is provided to 
prevent recurring abnormal termination. The format of the 
DEBCHK and a description of the operands folloM* 



DEBCHK— tIACRO SPECIFICATION 



Isymboll 


DEBCHK 


cbaddr 

C»TYPE=CVERIFY| : ADD IDELETEI PURGE}] 

[>AN=Camtypel (amaddr ) 1 ( (amreg) )}] 

i,branch={:no|yes}] 

C,TCBADDR=address] 
[»KEYADDR=addres5] 
[»SAVREG=req] 
I»MF=L] 



cbaddr 



for BRANCH=NO 

RX-type address, (2-12)* or (1) 

A control block address passed to the DEBCHK routine. This 
operand is ignored if MF=L is coded. For verify, add, and 
delete requests, cbaddr is the address of a DCB or ACB that 
points to the DEB uihose address is either verified to be in 
the DEB table, added to the DEB table, or deleted from the 
DEB table. For the purge function, cbaddr is the address 
of the DEB Mhose pointer is to be purged from the table? no 
reference is made to the DCB or ACB. 
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Note: A spooled DCB's DEB does not point back to the DCB> 
but to the spooled ACB; in this case* the DEBCHK should be 
issued against the ACB. 

for BRANCH=YES 

The A-type address of a 4-byte field* or a register 
(1) or (3-12), that points to the DCB or ACB 
containing the DEB to be verified. 

TYPE=CVEB1£Y I ADD {DELETE I PURGE} 

indicates the function to be performed. If MF=L is coded, 
TYPE is ignored. The functions ore' 

VERIFY 

This function is assumed if the TYPE operand is not 
coded. The control program checks the DEB table to 
determine whether the DEB pointer is in the table at 
the location indicated by the DEBTBLOF field of the 
DEB. The DEB is also checked to verify that DEBDCBAD 
points to the DCB (or ACB) passed to DEBCHK. The 
DEBAMTYP field in the DEB is compared to the AM 
operand value, if given. The two must be equal. 
TYPE=VERIFY can be issued in either supervisor or 
problem state. 

ADD 

The DEB and the DCB (or ACB) must point to each other 
before the DEB address can be added to the DEB table. 
Before the DEB pointer can be added to the table, the 
DEB itself must be queued on the current TCB DEB chain 
(the TCBDEB field contains the address of the first 
DEB in the chain). The DEB address is added to the 
DEB table at some offset into the table. That offset 
value is placed in the DEBTBLOF field of the DEB, and 
the access method type is inserted into the DEBANTYP 
field of the DEB, A zero is placed in the DEBAMTYP / 
field if the AM operand is not coded. TYPE=ADD can be (i 
issued only in supervisor state. ^^^ 

DELETE 

The DEB and the DCB (or ACB) must point to each other 
before the DEB address can be deleted from the DEB 
table. TYPE=DELETE can be issued only in supervisor 
state. 

PURGE 

The DEB pointer is removed from the DEB table without 
checking the DCB (or ACB)^ TYPE=:PURGE can be issued 
only in supervisor state. 

specifies an access method value. Each value corresponds 
to a particular access method type (note that BPAM and SAM 
have the same values) • 

Type value 



AN 



TCAMAP 


X»84» 


SUBSYS 


X»81' 


ISAM 


X'80' 


BDAM 


X'40» 


SAM 


X'20* 


BPAM 


X'20» 


TAM 


X'lO* 


GAM 


X'08» 


TCAM 


X'04' 


EXCP 


X'02' 


VSAM 


X»01» 


NONE 


X»00» 



The operand can be coded in one of the following three 
ways, only the first of which is valid for the list form 
(MF=L) of the instruction. 



../' 
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refers to the access method: XSAN> BDAM» SAN» SPAN* 
TAN (Mhich refers to BTAM only), GAM* TCAN, EXCP, or 
VSAN. TCANAP identifies a TCAM application-program 
DEB. SUBSYS identifies a subsystem of the operating 
system* such as a job entry subsystem. NONE indicates 
that no access method or subsystem is specified. 

(^m^d^r) 

is the RS-type address of the access method value. 
This format may not be coded when NF=L is used. 

C( amreg )l 

is one of the general registers 1 through 14 that 
contains the access method value in its loM-order byte 
(bit positions 24 through 31). The high-order bytes 
are not inspected. This form may not be used when 
NF=L is coded. 

The use of amaddr and amreg should be restricted to those 
cases uhere the access method value has been generated 
previously by the NF=L form of DEBCHK. If NF=L is not 
coded, the significance of the AM operand depends upon the 
TYPE. 

If TYPE is ADD and AN is specified, the access method value 
is inserted in the DEBANTYP field of the DEB, and all 
subsequent DEBCHK macros referring to this DEB must either 
specify the same AN or omit the operand. Uhen the AN 
operand is omitted for TYPE=ADD, a null value (0) is placed 
in the DEB and all subsequent DEBCHK macros must omit the 
AN operand. 

If AN is specified when the TYPE is PURGE» DELETE, or 
VERIFY, the access method value is compared to the value in 
the DEBANTYP field of the DEB. If AN is omitted, no 
^< comparison is made. 

BRANCH=CNO|YES} 

specifies whether you want to use the branch entry to the 
DEBCHK verify routines. 

NO 

specifies branch entry is not to be used. The 
operands SAVREG, TCBADDR, and KEYADDR are ignored. 

YES 

specifies the branch entry is to be used. TYPE=VERIFY 
must be implicitly or explicitly specified. The 
operands TCBADDR and KEYADDR are required. AM and MF 
are ignored. Hotes for BRANCH=YES5 

• Registers 1, 2, 10, 11, 14, and 15 must not be 
used for SAVREG=. 

• Registers 1, 2, 10, 11, 14, 15, and the register 
specified for SAVREG= must not be used for cbaddr, 
TCBADDR=, or KEYADDR=. 

• The contents of registers 10, 11, and 14 are 
unpredictable on completion. Also, if you do not 
specify SAVREG=, the contents of register 2 are 
unpredi ctable. 

• At completion time, register 1 contains the 
address of the DEB, and register 15 contains 
either 0, 4, or 16 (see beloM for codes and their 
meanings) . 

TCBADDR= address — A-type address or (3-12) 

specifies the location or register containing the address 
of the TCB to be used by the DEBCHK verify routine. Use 
this operand only when BRANCH=YES. 
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KEYADDR- address — A-type address or (3-12) 

specifies the location, or a register pointing to the ^.,^ 

location of a field containing the key to be used Mhen 4 ^, 

accessing the DCB (or ACB). Use this operand only Mhen 4 J^' 
BRANCH=YES. 

SAVREG=:re£| 

specifies the register in which register 2 i s to be saved. 
Use this operand only when BRANCH=YES. 

MF=L 

indicates the list form of the DEBCHK macro instruction. 
Mhen MF=L is coded, a parameter list is built consisting of 
the access method value that corresponds to the AM keyword. 
This value may be referenced by name in another DEBCHK 
macro by coding AN=(amaddr)> or it may be inserted into the 
low-order byte of a register before issuing another DEBCHK 
macro by coding AN=((amreg) ). 

If the DEBCHK routine completes successfully, register 15 will 
be set to and register 1 will contain the address of the DEB 
when control is returned to your program. Otherwise, register 
15 will contain one of the following decimal codes* 

Code Meaning 

4(04) Either (a) the DEB table associated with the job step 
does not exist; or (b) the DEBTBLOF field of the DEB 
was set to zero or a negative number, or was larger 
than the DEB table; or (c) register 1 did not contain 
the same address as the DEB table entry. 

8(08) An invalid TYPE was specified. (The DEBCHK routine was 
entered by a branch, not by the macro.) 

12(0C) Your program was not authorized and TYPE was not ^ ^ 

VERIFY. r \ 



16(10) DEBDCBAD did not contain the address of the DCB (ar 
ACB) that was passed to the DEBCHK routine. 

20(14) The AM value does not equal the value in the DEBAMTYP 
field. 

24(18) The DEB is not on the DEB chain and TYPE=ADD was 
speci f ied. 

28(1C) TYPE=ADD was specified for a DEB that was already 
entered in the DEB table. 

32(20) The DEB table exceeded the maximum size (32,760 bytes) 
and TYPE=ADD. 



PURGING AND RESTORING I/O REQUESTS 



The system's purge routines, guided by a parameter list you pass 
them, perform either a halt or a quiesce operation. In a halt 
operation, the purge routines stop the processing of specified 
I/O requests that were initiated with an EXCP macro instruction. 
In a quiesce operation, the purge routines: 

• Allow the completion of I/O requests that were initiated 
with an 

passed to the I/O supervisor for execution 

• Stop the processing of those requests that have not as yet 
been passed to the I/O supervisor, but save the lOBs of the 
requests so that they can be reprocessed (restored) later. 



\,.J^ 
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The system's restore routines make it possible to reprocess I/O 
requests that are quiesced. (Note* Not covered here is the 
purge and restore processing that takes in I/O requests not 
initiated by an EXCP macro instruction. If you want to knoM the 
full scope of purge and restore processing^ see I/O Supervisor 
logic.) 

You can give control to the purge and restore routines in tuo 
Mays: (i) by loading register 1 Mith the address of the 
parameter list and i ssui ng speci f i c SVC instructions or (2) by 
issuing the PURGE and RESTORE macro instructions. If your 
installation requires the use of macro i nstructi ons» you must 
add the macro definitions to the macro library (SYSl .MACLIB) or 
place them in a partitioned data set and concatenate this data 
set to the macro library. The macro definitions^ JCL» and 
utility statements needed to add the macros to your macro 
library are presented in Figure 36 , and Figure 37 on page 156. 
Mhether you issue the macro instructions or the SVC 
instructions* you must first build a parameter list. The SVC 
instructions are SVC 16 for PURGE and SVC 17 for RESTORE. 



PURGE Macro Definition 



MACRO 
«NAME PURGE 

AIF 
&NAME IHBINNRA 

SVC 

MEXIT 
.El IHBERMAC 

MEND 



«LIST 
('*LIST» 
4LIST 
16 

01,1^7 



EQ »').E1 

LOAD REG 1 



LIST ADDR MISSING 






control statements Required 



//jobname 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYSIN 

./ ADD 



JOB 

EXEC 

DD 

DD 

DD 



{parameter} 

PGM=IEBUPDTE,PARM=NEW 

SYSOUT=A 

DSNAME=SYS1. MACLIB, DISP=OLD 



NAME=PURGE,LIST=ALL 



PURGE macro definition 



./ ENDUP 
/x 

Figure 36. Macro Definition, JCL, and Utility Statements for 
Adding PURGE Macro to the System Macro Library 
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RESTORE Macro Definition 



""^ 



&NANE 
&NAME 



,E1 



MACRO 

RESTORE 

AIF 

IHBINNRA 

SVC 

MEXIT 

IHBERMAC 

MEND 



«LIST 
(•*LIST» 
«LIST 
17 

01^50 



EQ 'M.El 

LOAD REG 1 

ISSUE SVC FOR RESTORE 

LIST ADDR MISSING 



Control statements Required 



//jobname 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYSIN 

./ ADD 



JOB 

EXEC 

DD 

DD 

DD 



{parameters} 

PGM=IEBUPDTE,PARM=NEW 

SYSOUT=A 

DSNAME=SYS1 .MACLIB,DISP=OLD 

DATA 



NAME=RESTORE, LIST=ALL 



RESTORE macro definition 



./ ENDUP 
/x 

Figure 37. Macro Definition* JCL, and Utility Statements for 
Adding RESTORE Macro to the System Macro Library 



PURGE — HALT OR FINISH I/0-REQUEST PROCESSING 



The macro instruction used to call the purge routines is coded 
as folloMs: 






Csvmbol] 


PURGE 


parameter-list address 



parameter list address — RX-type address* (2-12) or (1) 

address of a parameter list* 12 or 16 bytes long* that you 
have built on a fullMord boundary in your storage. The 
parameter list address can be specified as an RX-type 
constant or in registers 2 through 12 or 1. 

The format and contents of the parameter list Br^ as follows! 

Byte Contents 

A byte in Mhich you specify what the purge routines 
will do. These Br^ the bit settings and their 
meanings! 



1... 
0... 

.1.. 
..1. 
...1 



Purge I/O requests to a single data set. 

Either purge I/O requests associated with 
a TCB or address space* or purge I/O 
requests to more than one data set. 

Post ECBs associated with purged I/O 
requests. 

Halt I/0-request processing. (Quiesce 
I/0-request processing* if 0.) 

Purge related requests only. (Valid only 
if a data-set purge is requested.) 
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Byte Contents 

.... 0... Reserved — must be zero. 

1.. Do not purge the TCB*s request-block chain 

of asynchronously scheduled processing. 

1. Purge I/O requests associated with a TCB. 

1 This is a 16-byte parameter list. 

Additional purge options are specified in 
bytes 12 to 15. (If this bit is off, the 
list is 12 bytes long, and the purge 
routines do not put a return code in byte 
4 of this list or in register 15.) 

1,2,3 The address of a DEB if you*re purging I/O requests to 
a single data set. The address of the first DEB in a 
chain of DEBs if you're purging I/O requests to more 
than one data set. (The next-to-the-last word of each 
DEB must point to the next DEB in the chain; the 
second Mord of the last DEB must contain zeros.) 

4 A byte of ?o»*os. (If bit 7 of byte is en,- the purgp 
routines will put a code in this bytei X*7F' if the 
purge operation is successful; X*40* if it is not 
successful . ) 

5,6,7 The address of the TCB associated with the I/O 

requests you want purged (but only if you turned on 
bit 6 of byte 0). Nay be zeros if the TCB is the one 
you're running under. 

8 A byte of zeros. 

9,10,11 The address of a word in your storage or the address 
of the DEBUSPRG field (which is X'll' bytes more than 
the DEB address in this parameter list). At whichever 
address you specify, the purge routines store a 
pointer to the purged I/O restore list, PIRL. In the 
PIRL is a pointer to the first lOB in the chain of 
lOBs. The location of the pointer and format of the 
chain are shown in Figure 38 on page 159 . 

12 A byte in which you can specify additional purge 
options. These are the bit settings and their 
meanings* 

Note: The following applies only if bit 7 of byte 
is set to one. 

, ,1 Purge I/O requests associated with an 

address space. (You must be in supervisor 
state.) 

...1 .... Check the validity of all the DEBs 

associated with the purge operation if 
this is a data-set purge. Validate this 
parameter list, whatever the type of purge 
operation, by ensuring that there are no 
inconsistencies in the selection of purge 
options. (If the caller is in problem 
state, these actions are taken regardless 
of the bit setting.) 

.... 1... Ensure that I/O requests will be 

reprocessed (restored) under their 
original TCB. (If zero and this byte is 
meaningful (bit 7 of byte is on), the 
I/O requests will be reprocessed under the 
TCB of the program making the restore 
request. ) 

0.. Must be zero. 
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Byte Contents 

13 A byte of zeros. 

14»15 The tMO-byte ID of the address space associated with 

the I/O requests you Mant purged. (Only meaningful if 
bit 2 of byte 12 is on.) 

Control Mill be returned to your program at the instruction 
following the PURGE macro instruction. If the purge operation 
Mas successfulf register 15 Mill contain zeros. OtherMise* 
register 15 Mill contain one of the folloMing return codes* 

Code Meaning 

4(04) Your request to purge I/O requests associated Mith a 
given TCB Mas not honored because that TCB did not 
point to the job step TCB» as it must Mhen the 
requestor is in problem state. 

8(08) Either you requested an address-space purge operation 
but Mere not in supervisor state» or you requested a 
data-set purge operation but supplied no data-area 
address in bytes 1» 2> and 3 of the purge parameter 
list. 

20(14) Another purge request has preempted your request. You 
may Mant to reissue your purge request in a 
time-controlled loop. 

Note: Register 15 Mill contain zeros» regardless of the outcome 
of the purge operation^ if you set bit 7 in byte of the 
parameter list to zero. 

HODZFYZNG THE XOB CHAIN /^ A 

( ,) 
Note> it is not a recommended procedure but» if you Mant to '^■^■^' 
change the order in Mhich purged I/O requests Mill be restored 
or prevent a purged request from being restored* you may change 
the sequence of lOBs in the lOB chain or remove an lOB from the 
chain. The address of the lOB chain can be obtained from the 
PIRL (see Figure 38 on page 159 . (The address of the PIRL Mill 
be at the location pointed to by bytes 9 through 11 of the purge 
parameter list.) 

RESTORE — REPROCESS I/O REQUESTS 

The RESTORE macro is coded as folloMS^ 



t symbol 3 


RESTORE 


restore address 



restore address — RX-type address » (2-12) or (1) 

address you specified at byte 9 of the purge parameter 
list. 
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PIRL 








PIRRSTR 20(14) 








Pointer to the first lOB. If l»s, 
no I/O request Mas quiesced. 














>I0B(1) 


(Mhere 1 is first lOB in chain) 





lOBRESTR 25C19) 



Pointer to the next lOB in the 
chain. 



' >IOB(n) ( 



[OB(n) 


(Mhere n is last lOB in chain) 




lOBRESTR 25(19) 






Contains binary l^s. 











^"*\,,^ 

\»^ 



Figure 38. The PIRL and lOB Chain 



PERFORMING TRAGIC CALCULATIONS 



The TRKCALC macro performs track capacity calculations. The 
standards list» execute^ and DSECT form of the macro are 
described. Examples of the TRKCALC macro folloM the macro 
descriptions. Using TRKCALC you may do the folloMing: 

• Perform track capacity calculations 

• Determine the number of records of a given size Mhich can be 
Mritten on a fulltrack or the remainder of a track 

• Perform track balance calculations as folloMs* 

— Determine if a given record size can be Mritten in the 
space remaining on the track and return the neM track 
balance. 

— Determine the maximum size record Mhich can be Mritten 
on the track if the given record does not fit. 

— Determine the track balance if the last physical record 
is removed from the track. 



Chapter 7. System Macro Instructions 159 



TRKCALC — STANDARD FORM 

The format of the TRKCALC macro iss 



[symbol I 


TRKCALC 


FUNCTN=CTRKBAL ITRKCAP} 

i , DEVTAB=addr | , UCB=addr | , TYPE=addr} 

C,BALANCE=addr] 

t, REMOVES C YES 1 NO}] 

[ , NAXS I ZE= C YESTnO} ] 

i f RKDD=addr | , R=addr , K=adcfr » I>D=adclr} 

[»REGSAVE=CYES|NO}] 

t,MF=I] 






FUNCTN=CTRKBAL ITRKCAP} 

specifies the function to be performed. 

Note: You must specify one of the three keyNords» DEVTABr 
UCB» or TYPE, to provide the macro a source for 
information. 

TRKBAL 

if REMOVE=NO is specified, TRKBAL calculates whether 
an additional record fits on the track, and Mhat new 
track balance Mould be if the record Mere added. If 
REMOVE=YES is specified, TRKBAL calculates Mhat the 
track balance Mould be if a record Mere removed from 
the track. The record to be added or removed from the 
track is defined by the RKDD parameter, or by the R, 
K, and DO parameters. 

If R=l (or the R value in the RKDD parameter is 1) and 
REMOVE=NO is specified, record 1 is added to an empty 
track; if R=l and REMOVE=YES is specified, record 1 is 
deleted from the track, leaving an empty track. 



removed 







Uhen REMOVE=NO 
occurs^ 



is specified, one of the folloMing 



• If the record fits on the track, register 
contains the neM track balance. 

• If the record does not fit on the track and 
MAXSIZE=NO is specified, a "record does not fit" 
return code is given in register 15. 

• If the record does not fit and MAXSIZE=YES is 
specified, one of the folloMing happens! 

— The data length of the largest record that 
fits in the remaining space is returned in 
register 0. 

— A code is returned that indicates no record 
fits in the remaining space. 

Uhen REMOVE=YES is specified, one of the folloMing 
occurs! 

• If R=l, register contains the track capacity. 

• If Rt^l, registers contains the input track 
balance (supplied through the BALANCE parameter) 
incremented by the track balance used by the input 
record. If the input balance is not supplied. 



c 



:> 
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register contains the track capacity left after 
R— 1 records are written on the track. 

TRKCAP 

calculates* and returns in register 0» the number of 
fixed length records that may be written on a whole 
track (R=l) or on a partially filled track (R#l). The 
records are defined by the K and DD values of the RKDD 
parameter* or by the K and DD parameters. 

One of the following occurs^ 

• If R=l» the BALANCE parameter is ignored and the 
calculation is made on an empty track. 

• If R^l and the BALANCE parameter is omitted* the 
calculation is made for a track that already 
contains R— 1 records of the length defined by the 
K and DD values. 

• If R^l^l and the BALANCE parameter is supplied* the 
calculation is made for a track whose remaining 
track balance is the value of the BALANCE 
parameter. 

DEVTAB=add|:— RX-type address* (2-12)* (0)* (14) 

addr specifies a word that contains the address of the 
Device Characteristics Table Entry (DCTE). If you specify 
a register* it contains the address of the DCTE* not the 
address of a word containing the address of the DCTE. The 
address of the DCTE can be found in the DCBDVTBA field of 
an opened DCB. 

UCB=addr— -RX-type address* (2-12)* (0)* (14) 

addr specifies a word that contains the address of the UCB. 
If you specify a register* it contains the address of the 
UCB* not the address of a word containing the address of 
the UCB. 

TYPE=add£— RX-type address* (2-12)* (0)* (14) 

you may specify the address of the UCB device type 
(UCBTBYT4)* or you may specify the one-byte UCB device type 
in the low-order byte of a register. 

BALANCE=addr — RX-type address* (2-12)* (0)* (14) 

you may specify either the address of a halfword containing 
the current track balance* or you may specify the balance 
in the low-order two bytes of a register. The value 
supplied may be the value returned when you last issued 
TRKCALC. If R=l* the balance Is reset to track capacity by 
TRKCALC and your supplied value is ignored. This is an 
input value and is not modified by the TRKCALC macro. The 
resulting track balance is returned in register and in 
the TRKCALC parameter list field STARBAL. 

RCHOVE=CYES|NQ> 

indicates if a record is to be deleted from the track. 



YES 



NO 



specifies the record number (specified in the R 
keyword) is being removed from the track. The track 
balance is incremented instead of decremented. 

Note: YES is valid only on a FUNCTN=TRKBAL call. 



specifies a record is not to be deleted from the 
track. NO is the default. 
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MAXSZZE=CYES|NO} 

YES' (f"\ 

If the specified record does not fit» the largest \^ 
length of a record with the specified key length that 
fits is returned (register 0). 



NO 



Note: YES is valid only on a FUNCTN=TRKBAL call. 



Maximum size i s not returned. NO is the default. 



RKDD=add£ — RX-type address, (2-12), (0), (14) 

addr specifies a Mord containing a record number (1 byte), 
keylength (1 byte), and data length (2 bytes) (bytes 0, 1, 
and 2 and 3, respectively) or a register containing the 
record number, key length, and data length. R, K, and DD 
may be specified by this keyword, or you may use the 
following three keywords instead. 

R=addr — RX-type address, (2-12), (0), (14), or n 

you may specify either the address of the record number, or 
you may specify the record number using the low-order byte 
of a register or immediate data (n). Specify a decimal 
digit for n (immediate data). 

K= addr — RX-type address, (2-12), (0), (14), or n 

you may specify either the address of a field containing 
the hex value of the record's key length, or you may 
specify the record's key length using the low-order byte of 
a register or rmmediate data (n). Specify a decimal digit 
for n (immediate data). 

DD= addr — RX-type address, (2-12), (0), (14), or n 

you may specify either the address of a field containing 
the hex value of the record's data length, or you may ^-^ 

specify the record's data length using the low-order two , 

bytes of a register or immediate data (n). Specify a X,^' 
decimal digit for n (immediate data). 

REGSAVE=CYES|NO} 

YES 

specifies registers 1 through 14 are saved and 
restored in the caller-provided save area (pointed to 
by register 13) across the TRKCALC call. Otherwise, 
registers 1, 9, 10, 11, and 14 &rG modified. 
Registers and 15 are always modified by a TRKCALC 
call. 



NO 



specifies registers are not saved across a TRKCALC 
call. NO is the default. 



HF=I 



specifies to define the storage for the TRKCALC parameter 
list and initialize the parameter list using the given 
keywords and call the TRKCALC function. MF=I i s the 
default. 



INPUT REGISTER USAGE FOR ALL FORMS OF 'MF* 



Registers 0» 2-12» and 14 are available to provide input for 
keywords. 

Register 1 is used only to provide the address of the parameter 
list for an MF=E call. 

Register 13 may be used as input for keywords, if RE6SAVE=YES is 
not specified. 



^(oibJ^ 
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Register 15 is used as a Mork register to build the TRKCALC 
parameter list for the MF=E call; it is not available as an 
input register. 



OUTPUT FROM TRKCALC 

FUNCTN=TRKBAL 



o 



Register 15=0 

The record fits on the track. Register and STARBAL 
contain the neM track balance. 

Register 15=^ 

Record does not fit on the track. If MAXSIZE=YE5 is 
specified^ a partial record does not fit either. 
Register and STARBAL are set to zero. 

Register 15=8 

Record does not fit on the track. MAXSIZE=YES is 
specified and a partial record does fit. Register 
and STARBAL are set to the maximum number of data 
bytes that fit on the remainder of the track with the 
specified keylength. 

Note: The keylength is excluded from the count of 
maximum data bytes. 

STARBAL 

This is the track balance field of the TRKCALC 
parameter list. This field is first set to the track 
capacity if R=l» or to the supplied BALANCE value if 
R^l» or to the calculated balance if R#l and BALANCE 
is omitted. STARBAL is updated to the new track 
balance if the record fits; otherwise^ STARBAL is left 
with the input track balance value. 



FUNCTN=TRKCAP 



TRKCALC — LIST FORM 



Register 15=0 

Register contains the number of records that fit on 
the track if R = 1» or the number of records that fit 
on the remainder of the track if R 'jft 1. 

Register 15=4 

No records of the length specified fit on a full track 
(R = 1) or a partial track (R # 1). Register is set 
to zero. 

STARBAL 

This is the track balance field of the TRKCALC 
parameter list. This field is first set to the track 
capacity if R=l» or to the supplied BALANCE value if 
R*l, or to the calculated balance if R*l and BALANCE 
is omitted. 



The list form of the TRKCALC macro is used to construct an 
empty* in-line parameter list. By coding only MF=L you 
construct a parameter list and the actual values can be supplied 
by the execute form of the TRKCALC macro. Any parameters other 
than MF=L are ignored. 



[symbol] 


TRKCALC 


MF=L 
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TRKCALC — EXECUTE FORM 



A remote parameter list is referred to and can be modified by 
the execute form of the TRKCALC macro. The TRKCALC routine is 
called. The description of the standard form of the macro 
provides the explanation of the function of each operand. 






[symbol] 


TRKCALC 


[ FUNCTN=CTRKBAL I TRKCAP} ] 
CC»DEVTAB=CaddrlK}| 

,UCB={addr|»}|,TYPE=Caddr|K>J3 
[,BALANCE=Caddr|)(}] 
[,RENOVE=€YES|NO}] 
[,NAXSIZE=CYES|N0}] 

[{•RKDD=addrl.R=addr>K=addr>DD=addrl] 
[,REGSAVE=CYES|NO}] 
,MF=(E,addr) 



FUNCTN=CTRKBAL | TRKCAP} 

it is coded as shown in the standard form. If this keyword 
is omitted^ &r\y specification of REMOVE^ MAXSIZE> LAST» and 
the RX form of BALANCE^ is ignored. In addition* DEVTAB is 
assumed* if UC5 is codcsd and a failure occurs, if TYPE is 
specified. Uhen you use FUNCTN, one of the keywords 
(DEVTAB, UCB» or TYPE) must be specified to provide an 
information source. 

DEVTAB=addr|X— RX-type address, (2-12), (0), (14) 

it is coded as shown in the standard form except for the X 
subparameter. Specify an ^ when you have inserted the 
address of the Device Characteristics Table Entry (DCTE) in 
the parameter list. 

UCB= addr lx — RX-type address, (2-12), (0), (14) 

it is coded as shown in the standard form except for the * 

subparameter. Specify an ^ when you have inserted the 

address of the UCB in the parameter list. 

TYPE= addr lX — RX-type address, (2-12), (0), (14) 

it i s coded as shown in the standard form except for the ^ 
subparameter. Specify an ^ when you have inserted the 
address of the UCB type (UCBTYP) in the parameter list. 

BALANCE=a£ldr|« — RX-type address, (2-12), (0), (14) 

it is coded as shown in the standard form except for the * 
subparameter. Specify an x when you have inserted the 
balance in the parameter list. 

RENOVE=CYES|NO} 

it is coded as shown in the standard form. 

MAXSXZE=CYES|NO} 

it is coded as shown in the standard form. 

RKDD= addr — RX-type address, (2-12), (0), (14) 

it is coded as shown in the standard form. 

R=addr— RX-type address, (2-12), (0), (14) or n 
it is coded as shown in the standard form. 

K=addr~-RX-type address, (2-12), (0), (14), or n 
it is coded as shown in the standard form. 

DD= addr — RX-type address, (2-12), (0), (14), or n 
it is coded as shown in the standard form. 

REGSAVE=CYES|Ng} 

it is coded as shown in the standard form. 



w 
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MF=(E, addr) 

this operand specifies that the execute form of the TRKCALC 
macro instruction is used* and an existing data management 
parameter list is used. 



TRKCALC — DSECT ONLY 



Coded as shoMn 

addr — RX-type address, (0), (1), (2-12), or (l<i) 

specifies an in-storage address of the parameter list. 



This call gives a symbolic expansion of the parameter list for 
the TRKCALC macro. No DSECT statement is generated. If a name 
is specified on the macro call, it applies to the beginning of 
the list, after any necessary boundary alignment. The macro 
generated symbols all begin Mith "STAR". 



[symbol] 


TRKCALC 


NF=D 



TRKCALC HACRO EXAMPLES 






In this example, TRKCALC is coded to determine hoM many records 
of a given size Mith 10-byte keys fit on a 3330 track. After 
issuing the macro, the number of records is saved in NUMREC: 

TRKCALC FUNCTN=TRKCAP , TYPE=UTYPE, R=l , K=10 , DD=DL , MF=( E( 1 ) ) 



ST 0,NUMREC SAVE NUMBER OF RECORDS 



DL 


DC 


H'xxxx' 


DATA LENGTH 


UTYPE 


DC 


X»09' 




NUMREC 


DS 


F 


MAX t OF RECORDS 



In this example, TRKCALC is coded to determine if another record 
can fit on a track of a 3350, given a track balance. 

TRKCALC FUNCTN=TRKBAL,TYPE=UTYPE,R=REC,K=KL,DD=DD,BALANCE=BAL, 
MAXSIZE=YES,MF=(E(1)) 



UTYPE 


DC 


X»OB' 


REC 


DC 


X'xx' 


KL 


DC 


X'xx' 


DD 


DC 


H * xxxx ' 


BAL 


DC 


H'xxxx' 



After issuing the macro, you Mould receive either : 

Register 15=0. Register contains the neM balance. 

Register 15=4. Register 0=0 (record did not fit). 

Register 15=8. Register contains the maximum data length that 

does fit (record did not fit). 



ALLOCATING A DATA SET 






The REALLOC macro builds a parameter list and issues SVC 32 to 
allocate a neN data set based on a partial DSCB that describes 
the attributes of that data set. You can use the OBTAIN macro 
to get the format-1 DSCB of the other data set and use it as a 
model for the neM data set's DSCB Mhich REALLOC Mill construct 
and Mrite in the VTOC. 
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The iTiaximum number of extents that may be allocated are 
determined by the type of data set requested as defined by the 
data set organization (DSIDSORG) bytes and the data set 
indicator (DSIDSIND) byte in the partial DSCB. If the DSIDSORG 
indicates a VSAM data set organization and DSIDSIND indicates 
the data set is cataloged in an integrated catalog facility 
(ICF) catalog^ the maximum number of extents Mill be 123. 
Otheruiise* the maximum number of extents Mill be 16. 

Note: User label data setsr ISAM data sets» and absolute track 
allocated data sets are not supported by the REALLOC macro. If 
a VSAM data set or data space is requested* REALLOC does not 
interface Mith VSAM or ICF catalog management. 

The DSISCALO field of the partial format-1 DSCB has a high order 
flag byte that describes the type of request and a 3-byte field 
containing the secondary allocation quantity. The folloMing 
describes the flag byte* 

Contents Meaning 

X*CO» Cylinder request 

X*C8" Cylinder Mith CONTIG request 

X»80* Track request 

X»88; Track Mith CONTIG request 

X*40* Average block length request 

X*41' Average block length Mith ROUND request 

X*48» Average block length Mith CONTIG request 

X»49» Average block length Mith CONTIG and ROUND request 

Any settings other than the above Mill be ignored. 

The REALLOC macro may be coded in the execute* dsect* and list 
forms* but not the standard form. The calling program may be in 
supervisor or problem program state* and may be running in any 
key. The calling program must be APF authorized. 

REALLOC — EXECUTE FORM 

The format of the REALLOC macro in execute form \s' 



C' 






[symbol 


REALLOC 


NF=(E*addr) 

•DSSIZE=addrl(req) 

,PDSCB=addr 

,UCB=addr 

C,MINAU=addr|(req) 

t,PDSDIR=addrr(reg) 



MF=(E,addr) 

specifies that the execute form of the macro and an 
existing REALLOC parameter list Mill be used. 

addr — RX-type address* (0-12) 

specifies an in-storage address of the REALLOC 
parameter list. 



Code as shoMn. 



J" 
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DSSIZE= addr l(reg) 

specifies the size of the data set to be allocated in 
tracks. If a cylinder request (X'CO* in the flag byte of 
DSISCALO) or average block uiith round request (X'41*) is 
made^ the number of tracks specified Mill be rounded up to 
the next full cylinder* if necessary. 

You may not specify the DSSIZE in terms of average block 
size* even though the original data set may have been 
allocated Mith the number of average blocks (X*40*). 

addr — RX-type address 

specifies an in-storage address of a full Mord 
containing the data set size. 

(rea) 

specifies a register containing the size of the data 
set. Valid registers are and 2-12. 

PDSCB=addr — RX-type address, (0), (2-12) 

specifies the address of the partial DSCB. The partial 
DSCB is comprised of the first 98 bytes of a format-1 DSCB. 
The first 44 bytes contains the data set name to be 
allocated. The contents of the partial DSCB Mill be used, 
unchanged* in constructing the format-1 DSCB. Only the 
field DSINOEPV (number of extents on the volume) of the 
partial format-1 DSCB Mill be modified by allocation to 
reflect the actual number of extents allocated. 

UCB= addr — RX-type address, (0), (2-12) 

specifies the address of the UCB of the volume Mhere the 
data set is to be allocated. The volume must be mounted 
and the caller is responsible for ensuring that the volume 
remains mounted on the unit. 

MINAU= addr l(reg) 

specifies the size of the minimum allocation unit in 
tracks. All primary extents for this data set Mill be in 
multiples of this minimum allocation unit. This value Mill 
not apply to subsequent extensions of the data set. If the 
partial DSCB indicates the data set is to be allocated in 
cylinders (X'CO* or average block Mith round request 
(X'^l*), this parameter Mill be ignored. 

addr — RX-type address 

specifies an in-storage address of a full Mord 
containing the minimum allocation unit. 

( req ) 

specifies a register containing the minimum allocation 
unit. Valid registers are and 2-12. 

PDSDIR= addr i(reg) 

specifies the number of 256 byte directory blocks for a 
partitioned data set (PDS). This is a required keyMord if 
the DSIDSORG indicates a partitioned data set. OtherMise, 
it is ignored. 

addr — RX-type address 

specifies an in-storage address of a full Mord 
containing the number of 256 byte PDS directory 
blocks. 

( req ) 

specifies a register containing the number of 256 byte 
PDS directory blocks. Valid registers ar& and 2-12. 
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RETURN CODES FROM REALLOC 



Control will be returned at the instruction following the SVC 32 

generated by the REALLOC macro. If the data set Mas successfully 

allocated^ register 15 Mill contain zeros. OtherMise* register 

15 will contain one of the folloMing return codes: 

Code Meaning 

004(04) Data set name of request already exists on this 

volume. Initial allocation not possible under the 
name given. 

008(08) No room available in the VTOC or VTOC index. 

012(00 One of the folloMing errors Mas encountered: 

• Permanent I/O error 

• Error returned by CVAF 
020(14) Requested quantity not available. 
028(10 ISAM DS0R6 is not supported. 
Code Meaning 

048(30) Invalid REALLOC parameter list. 

052(34) Invalid partial DSCB pointer. 

056(38) Not enough space on volume for directory. 

072(48) DOS VTOC cannot be converted to an OS VTOC. 

116(74) User labels not supported. 

120(78) DSSIZE=0 and MINAU is greater than 0. 

124(7C) DSSIZE i s not a multiple of MINAU. 

128(80) Directory space requested is larger than primary 
space. 

148(94) Overlapping extents in the VTOC. 

152(98) Overlapping DOS split cylinder extents in the VTOC. 

156(9C) DADSM allocation terminated due to possible VTOC 
errors. 

164(A4) Allocation terminated due to DOS stacked pack format. 

168(A8) RACF DEFINE failed* data set already defined. 

172(AC) User not authorized to RACF define data set. 

176(B0) Installation exit rejected this request Mith a return 
code of 8. 

180(B4) Installation exit rejected this request Mith a return 
code of 4. 






'\-^' 



-.y 
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REALLOC— D8ECT ONLY 



Tho dsoct form of REALLOC is specificid as follows: 



Isvmbol 


REALLOC 


NF=D 



An exampla of tho dsect form expansion is^ 



REALPL 


REALL 


DC MF=D 


REALPL 


DSECT 




RALPLID 


DS 


CL4 


RALNGTH 


DS 


AL2 


RAERRCDE 
RALRSVD 


DS 


H 


DS 




RALDSSZ 


DS 




RALMAU 


DS 




RALPDSCB 


DS 




RALUCB 


DS 




RALDQTY 


DS 




RALEND 


EQU 


X 


RALENGTH 


EQU 


RALEND 



DSECT FOR PARAMETER LIST 

EBCDIC *REAL* FOR REALLOC 

LENGTH OF PARAMETER LIST 

ERROR CODE RETURNED FROM 

ALLOCATE (SVC 32) 

RESERVED 

DATA SET SIZE 

MINIMUM ALLOCATION UNIT 

PARTIAL DSCB POINTER 

UCB POINTER 

PDS DIRECTORY QUANTITY 

END OF PARAMETER LIST 

LENGTH OF PARAMETER LIST 



REALLOC — LIST FORM 



The list form of the REALLOC macro is specified as follows: 



g^ 



Isvmbol 


REALLOC 


MF=L 

,DSSIZE=addi:|(|:sSl) 

»PD&CB=addr 

,UCB=addr . • ^ 

I,MINAU=add£|(j:sfl) 

[>PDSDIR=sdji£|(r£a) 



Refer to the execute form for an explanation of the parameters. 
An example of the list form expansion is: 



REALPL 


REALLOC MF=L 




CHOP 0»4 


REALPL 


EQU X 




DC CL4»REAL» 




DC AL2(32) 




DC H » ' 


X 






DC F'O* 




DC F'O' 




DC F*0» 




DC A(0) 




DC A(0) 




DC F'O' 


RALOIE 


EQU X 



EBCDIC *REAL' FOR REALLOC 

LENGTH OF PARAMETER LIST 

ERROR CODE RETURNED FROM 

ALLOCATE (SVC 32) 

RESERVED 

DATA SET SIZE 

MINIMUM ALLOCATION UNIT 

PARTIAL DSCB POINTER 

UCB POINTER 

PDS DIRECTORY QUANTITY 

END OF PARAMETER LIST 
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CHAPTER 8. MAINTAINING SYSI.IMAGELIB 



This chapter describes hoM to maintain the system image library 
(SYSI.IMAGELIB) UCS and FCB images for the 1<»03, 3203, and 3211 
printers. It also describes hoM to maintain FCB images for the 
4245 printer, the UCS image table in SYSI.IMAGELIB for the 4245, 
and hou to retrieve an FCB image from SYSI.IMAGELIB in order to 
modify it. 

The lEBIMAGE utility program is used to create and maintain 
control modules for the 3800 printing subsystem* character 
arrangement table modules, graphic character modification 
modules, copy modification modules, library character set 
modules, and FCB modules. For further information on lEBIMAGE, 
see Uti li ties . 

To use the information presented in this chapter, you should be 
familiar Mith the subjects of the following publications* 

• Data Management Macro Instructions describes the SETPRT 
macro, which can specify the UCS and/or FCB images to be 
used. 

• JCL describes the UCB and FCB parameters of the DD 
statement, which are processed at OPEN time. 

• IBM 2821 Control Unit Component Description contains 
information on creating a user-designed chain/train for the 
1403 printer. 

• IBM 3203 Printer Component Description and Operator's Guide 
contains information on creating a user-designed train for /f"\^ 
the 3203 printer. 1^^ 

• IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 
3811 Printer Control Unit Component Description and 
Operator|s Guide contains information on creating a 
user-designed train for the 3211 printer. 

• System Programming Library* JES2 or System Programming 
Library* Network Job Entry Facility for JES2 contains 
reference information for JES2. 

• System Programming Library* JES3 contains reference 
information for JES3. 

The 4245 printer has no UCS images supplied in SYSI.IMAGELIB. 
To determine which UCS images sroi available, see: 

• IBM 4245 Printer Model 1 Component Description and 
Operator's Guide contains information on band IDs for the 
4245 printer. 

The SPZAP service aid can be used to display and modify an 
existing member of SYSI.IMAGELIB. Use of SPZAP on load modules 
is described in System Programming Library^ Service Aids . 



UCS IMAGES IN SYSI.IMAGELIB 



Most IBM standard character set images are included in 
SYSI.IMAGELIB at system generation time, through the DATAMGT 
macro and an lODEVICE macro for the specified printer. (See 
System Generation Reference for details on the DATAMGT and 
lODEVICE macros.) The standard character set images for the 
1403, 3203, and 3211 printers are shown in the table below. 
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Printer 


Images 


1403 or 3203 


AN, HN, PCAN, PCHN, PN, QNC, QN, RN, 
TN, XN, YN 


SN, 


3211 


All, Gil, Hll, Pll, Til 



o 



For the 4245, no UCS images are supplied in SYSl . IMAGELIB at 
system generation. Instead, a neM UCS image is loaded into the 
buffer at pouiei — on time or whenever the operator mounts a new 
band. See **Adding a UCS Image Name/Alias to a UCS Image Table" 
on page 175 for information on how to access UCS images that are 
not supplied in SYSl . IMAGELIB. 

The 4245 printers also load a default FCB image at power-on 
time. For the 4245, the default FCB is an 11-inch form with 6 
LPI and a Channel 1 on the first print line. 

The alias names are defined for most installation-standard print 
chains/trains/bands installable on a given printer. Alias names 
are included in SYSl. IMAGELIB (in the UCS imasc tabla) at systsj^ 
generation time, with the real name of each image. 

Some print chains/trains/bands, such as SN and Gil, do not have 
alias names because there is no equivalent chain/train/band on 
other printers. You can assign an alias for these 
chains/trains/bands with the ALIAS statement of the linkage 
editor. (See Linkage Editor and Loader for more information on 
the ALIAS statement.) For the 4245 printer, you can also add an 
alias name by modifying an entry in the UCS image table. See 
"Adding a UCS Image Name/Alias to a UCS Image Table" on page 
175. 

If an alias name is supplied, it is used to schedule a printer 
for SYSOUT data sets. If no alias is supplied, an 
installation-defined SYSOUT class or a printer routing code 
(specified with the DEST parameter of JCL) should be used to 
assign the data set to the correct printer. 



ADDING A UCS IMAGE TO THE IMAGE LIBRARY 



Using the assembler and linkage editor, you may add a UCS image 
to those that reside in SYSl . IMAGELIB. No executable code is 
generated; the assembler prepares DCs and the linkage editor 
puts them into SYSl . IMAGELIB . The new UCS image must be 
structured according to the following rules^ 

1. The member name must be 5 to 8 characters long; the first 4 
characters must be the appropriate UCS prefix, as shown 
below. 

UCSl - 1403 printer 

UCS2 - 3211 printer 

UCS3 - 3203 printer 

These first 4 characters must be followed by a character set 
code, 1 to 4 characters long. Any valid combination of 
letters and numbers under assembler language rules is 
acceptable. However, the single letters U or C must not be 
used, because they are symbols for special conditions 
recognized by the system. The assigned character set code 
must be specified on the DD statement or SETPRT macro to 
load the image into the UCS buffer. 

You can supply an alias name for a new image with the ALIAS 
statement of the linkage editor. (See Linkage Editor and 
Loader for more information on the ALIAS statement.) 
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The first byte of the character set image load module 
specifies whether the image is a default. (Default images 
may be used by the system for jobs that do not request a 
specific image.) Specify the following in the first byte: 



T\ 



For JES2: 

X'80» 

X»40' 

X»CO» 

X'OO' 
default 



indicates a default image 

indicates that the output is to be folded 

indicates default image and folding 

indicates that the image is not to be used as a 



For non-JES25 

X*80* indicates a default image 

X*00' indicates that the image is not to be used as a 
default 

The second byte of the load module indicates the number of 
lines (n) to be printed for image verification. See 
"Verifying the UCS Image" on page 178 for more information 
on image verification. 

Each byte of the next n bytes indicates the number of 
characters to be printed on each verification line. For the 
3211 printer^ the maximum number of characters printed per 
line is 48; the bytes of associative bits (see note 5) etro 
not printed during verification. 

The UCS image itself must follow the previously described 
fields. The image must fill the number of bytes required by 
the printer; see the table below for image lengths. Note 
that> because of assembler language syntax> two apostrophes 
or two ampersands must be coded to represent a single 
apostrophe or a single ampersands respecti vely> within a 
character set image. 






Printer 


Image Length 


1403 


240 bytes 


3203 


304 bytes (240 characters followed by 64 
bytes of associative bits) 


3211 


512 bytes (432 characters followed by 15 
bytes of X*00*» 64 bytes of associative 
bits» and one reserved byte of X*00*) 



Associative bits must be coded to prevent data checks when 
adding a UCS image to SYSl . IMAGELIB. See the appropriate 
printer manual for more information on coding associative 
bits. 

Figure 39 on page 173 contains an example of adding a 1403 UCS 
image* YN, to SYSl . IMAGELIB. Notes follow Figure 41 on page 
174. 
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//ADDYN 

//STEP 

// 

//ASM.SYSIN 

UCSIYN 



JOB MSGLEVEL=1 

EXEC PROCsASMFCL^PARM.ASMs'NODECKaOAD", 

PARM.LKED=» LIST, OL,REFR, RENT, XREF» 
DD X 
CSECT 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 



X»80» 

AL1(6) 

AL1(39) 

AL1(42) 

AL1(39) 

AL1(39) 

AL1(42) 

AL1(39) 



(THIS IS A DEFAULT IMAGE) 
(NUMBER OF LINES TO BE PRINTED) 
(39 CHARACTERS TO BE PRINTED ON LINE 1) 
(^2 CHARACTERS TO BE PRINTED ON LINE 2) 
(39 CHARACTERS TO BE PRINTED ON LINE 3) 
(39 CHARACTERS TO BE PRINTED ON LINE 4) 
(42 CHARACTERS TO BE PRINTED ON LINE 5) 
(39 CHARACTERS TO BE PRINTED ON LINE 6) 



THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE 



/x 

//LKED.SYSLMOD 
// 



DC 
DC 
DC 
DC 
DC 
DC 
END 

DD 



I 



C»1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX,. 
CU23A567890STABCDEFGHIJKLMNOPQRSTUVWXYZX,. 
C» 123<i567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . 
C'123<»567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . • 
C»1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX,.t-$» 
C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . • 



DSNAME=SYS1.IMAGELIB(UCS1YN),DISP=0LD, 
SPACE= (OVERRIDE SECONDARY ALLOCATION) 



Figure 39. Sample Code to Add a 1<»03 UCS Image to SYSl .IMAGELIB 



Figure 40 shoMs the code used to add a 3203 UCS image, YN, to 
the image library. 






//ADYN3203 

//STEP 

// 

//ASM.SYSIN 

UCS3YN 



/M 



JOB MSGLEVEL=1 

EXEC PROC=ASMFCL,PARM.ASM=»NODECK,LOAD», 

FARM. LKED=» LIST, OL,REFR, RENT, XREF* 
DD ii 
CSECT 

DC X»80» (THIS IS A DEFAULT IMAGE) 
DC AL1(6) (NUMBER OF LINES TO BE PRINTED) 
DC AL1(39) (39 CHARACTERS TO BE PRINTED ON LINE 1) 
DC AH(42) (42 CHARACTERS TO BE PRINTED ON LINE 2) 
DC AL1(39) (39 CHARACTERS TO BE PRINTED ON LINE 3) 
DC AL1(39) (39 CHARACTERS TO BE PRINTED ON LINE 4) 
DC AL1(42) (42 CHARACTERS TO BE PRINTED ON LINE 5) 
DC AL1(39) (39 CHARACTERS TO BE PRINTED ON LINE 6) 
THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE 

DC C*1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . » 
DC C»1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX,.t-$» 
DC C»1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . • 
DC CU234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . » 
DC C'1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX,.t-$» 
DC CU234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . » 
THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS, 
UCSB BYTE POSITIONS 241-304 

DC X*C01010101010101010100040000000000010< 

X' 101010101010101000404000000040001010* 

X* 101010101010004000000000101010101010* 

X' 10101010004000000000' 



DC 
DC 
DC 
END 



//LKED.SYSLMOD DD 
// 



DSNAME=SYS1.IMAGELIB(UCS3YN),DISP=0LD, 

SPACE= (OVERRIDE SECONDARY ALLOCATION) 



Figure 40. Sample Code to Add a 3203 UCS Image to SYSl. IMAGELIB 
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Figure 41 shoMS the code used to add a 3211 UCS imager All» to 
SYSl.IMAGELIB. 

//ADDAll JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCL, FARM. ASM='NODECK, LOADS 

// FARM. LKED=^'' LIST, OL,REFR, RENT, XREF* 

//ASM.SYSIN DD X * 

UCS2AH CSECT 

DC X'80» (THIS IS A DEFAULT IMAGE) 

DC AL1(9) (NUMBER OF LINES TO BE PRINTED) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 1) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 2) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 3) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 4) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 5) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 6) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 7) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 8) 

DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 9) 

X THE FOLLOWING NINE LINES REPRESENT THE TRAIN IMAGE 

X NOTE 2 AMPERSANDS MUST BE CODED TO GET 1 IN ASSEMBLER SYNTAX 

DC C'l<.+IHGFEDCBA)«$-RQPONMLKJ%,*iZYXWVUTS/a»098765432» 

DC C»l<.+IHGFEDCBAJ<$-RQPONMLKJ%,&&ZYXWVUTS/a»098765432» 

DC C»l<.+IHGFEDCBAX$-RQPONMLKJ%,«&ZYXWVUTS/a»098765432' 

DC C»l<.+IHGFEDCBAX$-RQPONMLKJ%,&&ZYXWVUTS/a»0 98765432 » 

DC C»l<.+IHGFEDCBAJ«$-RQP0NMLKJ%,&&ZYXWVUTS/a»098765432' 

DC C'l<.+IHGFEDCBAX$-RQPONMLKJX,«iZYXWVUTS/a»098765432' 

DC C 1< . +IHGFEDCBAK$-RQPONMLKJ%, &«ZYXWVUTS/a to 98765432 ' 

DC C»l<.+IHGFEDCBAX$-RQPONMLKJ%,&«ZYXWVUTS/a«098765432» 

DC C»l<.+IHGFEDCBAJ($-RQPONMLKJ%,&&ZYXWVUTS/a«0 98765432' 

DC 15X»00» (RESERVED FIELD, BYTES 433-447) 

X THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS, 

X UCSB BYTE POSITIONS 448-511 

DC X<'C01010101010101010100040404240004010* 

DC X'101010101010101000404041000040401010' f 

DC X*101010101010004040000000101010101010' \ 

DC X»10101010004040444800' 

DC X»00» (RESERVED FIELD, BYTE 512) 

END 

/x 

//LKED.SYSLMOD DD DSNAME=SYS1 . IMAGELIB(UCS2A11 ) ,DISP=OLD, 

// SPACE= (OVERRIDE SECONDARY ALLOCATION) 

Figure 41. Sample Code to Add a 3211 UCS Image to SYSl.IMAGELIB 



Notes to Figure 39 on page 173» Figure 40 on page I73t and 
Figure 41: 

1. The RENT and REFR linkage editor attributes ar& used for 
performance considerations in a paging environment. They 
may be omitted. 

2. For the 3203 and 3211 printers, the 64 bytes of associative 
bits must be coded to avoid data checks. To determine hoM 
to code these bits for a particular image, see IBM 3203 
Printer Component Description and Operator's Guide or IBM 
3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 
Printer Control Unit Component Description and Operator's 
Gui de . 

3. Executing the ASMFCL procedure does not actually generate 
executable code. The assembler/linkage editor is used to 
place the UCS image into SYSl.IMAGELIB. 

4. The SPACE parameter is overridden here because the ASMFCL 



\..J^ 



cataloged procedure has secondary allocation specified. iff^'^ 
Elimination of the override causes the original secondary '\^jJ 
allocation amount to be used. 
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ADDING A UCS IMAGE NAME/ALIAS TO A UCS IMAGE TABLE 



For the 4245 printer^ no UCS images are stored in SYSl .IMAGELIB. 
Instead* the image for each band is stored in the printer* and 
automatically loaded into the UCS buffer at pouer-on time or 
uihen a neM band is installed. Information about these images is 
recorded in the IBM-supplied UCS image table* Mhich resides in 
SYSl. IMAGELIB. 



UCS Image Table structure 



SYSl. IMAGELIB contains one UCS image table for each type of 
printer that supports image tables. For the 4245* the table is 
called UCS5. The image table contains an entry for most 
installation-standard IBM-supplied bands. A typical UCS image 
table entry takes the form shoMn in Figure 42. 



Byte 1 



9 10 11 12 



16 17 



-ih 



-ih 



32 



I 



■ih 



Description data'' 
^ Length of description data'* 



-^ Lengths of verification lines^ 
(V LENGTH); one byte per line 



-^ Number of verification lines^ 

-^ Reserved (set to zero) 

-^ Description offset (set to zero if omitted) 

-^ Verification offset (set to zero if omitted) 

-^ Flag Byte: X'OO' ° Non-default image 
X'80' ■■ Default image 

-7 UCS Image Name 

-^ UCS Image Name or Alias (1-4 character 
name, left-justified and padded to a 
4-character length with blanks, if necessary) 

-7 Length of this entry 



Figure 42. UCS Image Table Entry Format 



Notes to Figure 42: 

1. This field is optional. 

2. This field is optional for the 4245 printer. 

The contents of the UCS image table UCS5 (IGGUCS5 macro)* for 
the 4245 printer* are shoMn in Figure 43. 
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Name 


Alias 


Default 


Description 


AN21 


AN21 


YES 


Default UCS image 


AN21 


AN 


NO 


1403/3203 AN image 


AN21 


All 


NO 


3211 All image 


AN21 


<J0E1 


NO 


4248 40E1 image 


HN21 


HN21 


NO 


Nondefault UCS image 


HN21 


HN 


NO 


1403/3203 HN image 


HN21 


Hll 


NO 


3211 Hll image 


HN21 


4101 


NO 


4248 4101 image 


PL21 


PL21 


NO 


Nondefault UCS image 


PL21 


PN 


NO 


1403/3203 PN image 


PL21 


Pll 


NO 


3211 Pll image 


PL21 


4121 


NO 


4248 4121 image 


SN21 


SN21 


NO 


Nondefault UCS image 


SN21 


4201 


NO 


4248 4201 image 


TN21 


TN21 


NO 


Nondefault UCS image 


TN21 


TN 


NO 


1403/3203 TN image 


TN21 


Til 


NO 


3211 Til image 


TN21 


4181 


NO 


4248 4181 image 


GN21 


GN21 


NO 


Nondefault UCS image 


GN21 


Gil 


NO 


3211 Gil image 


GN21 


41C1 


NO 


4248 41C1 image 


RN21 


RN21 


NO 


Nondefault UCS image 


RN21 


RN 


NO 


1403/3203 RN image 


KA21 


KA21 


NO 


Nondefault UCS image 


KA21 


4041 


NO 


4248 4041 image 


KA22 


KA22 


NO 


Nondefault UCS image 


FC21 


FC21 


NO 


Nondefault UCS image 


FC21 


4161 


NO 


4248 4161 image 






Figure 43. UCS5 Image Table Contents 



Note: The image table for the 4245 printer includes USA and 
Canada band IDs only. To support other national band IDs> you 
Mill have to modify the UCS image table. See "Adding/Modifying 
a UCS Image Table Entry." 



Adding/Nodifying a UCS Image Table Entry 



If you plan to use a new UCS image name/alias with the 4245 
printer* you must add an entry for that image name/alias to the 
appropriate UCS image table. Similarly* if you want to select a 
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noM default imaga or change the description on an old imager you 
must make the change in the image table. 

To build new UCS table entries^ or to change the format of old 
entries* use the following procedure: 

1. Issue the IGGUCSIT macro* as described beloM* to build a new 
UCS image table entry. A new entry is built even if it is 
intended to replace an existing entry supplied by IBM. 
Because the neN entry is found first* the previous entry is 
never found and thus is effectively replaced. 

2. Include the UCS image table* source using the macro IGGUCS5* 
which is found in SYSl.MACLIB. 

3. Reassemble the image table module (UCS5). 

4. Link-edit the reassembled module into SYSl . IMAGELIB. 
The IGGUCSIT macro instruction has the following format ^ 



IGGUCSIT 



MF=CLISI|DSECT} 
» NAMES image name 
ItALIAS= image alias ! 

c,default=<:yes|ns}] 

[ t DESCR= descr i pt i on 1 
[,VLENGTH=(nl*n2,. . .n)] 



MFst LIST lDSECTl 

specifies the form of the macro instruction. 



LIST 



produces a UCS image table entry based on the 
information supplied in other IGGUCSIT parameters. 
LIST is selected or allowed to default* the NAME 
parameter must also be coded. 



If 



DSECT 

produces a DSECT for a single UCS image table entry* 
similar to the sample entry shown in Figure 42 on page 
175. If DSECT is coded* all other parameters of 
IGGUCSIT are ignored. 

LIST is the default. 

NAMES image name 

specifies the 1- to ^-character UCS image name. 

ALI AS= i mage a 1 i as 

specifies a 1- to 4-character alias name for the UCS image. 
If ALIAS is not specified* the image name coded in the NAME 
parameter will be entered in the UCS image table. 

DEFAULT={YES|Ng} 

indicates whether the new UCS image is to be used as a 
default value. 



YES 



NS 



indicates that this UCS image is a default. Default 
images are used by the system for jobs that do not 
request a specific image. 



indicates that this UCS image should not be used as a 
default. 



If the DEFAULT parameter is not specified* the new UCS 
image is not used as a default. 
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DESCRs descr j pt i on 

specifies descriptive information about the neui UCS image. 
description can be up to 32 EBCDIC or hexadecimal 
characters in lengths although EBCDIC and hexadecimal 
characters cannot be used in combination. 

The descriptive information is placed in the header line of 
the verification display* folloMing the real UCS image 
name. If the DESCR parameter is omitted* no description 
Mill appear in the display. For more information on the 
verification display* see "Verifying the UCS Image." 

If VLENGTH is not specified for the 4245 printer, the DESCR 
parameter is ignored. 

VLENGTH=(nl,ji£,. . . n) 

specifies the length(s) of each line in the UCS 
verification display. The length of each line must be 
specified separately* even if all lines are the same 
length. 

nl is the length of print line 1; n2 is the length of print 
line 2* n is the length of the last print line. The sum of 
the verification line lengths should be equal to 350 in 
order to display the complete image. 

See "Verifying the UCS Image" for details on the 
verification report. 



Verifying the UCS Image 



For the 1403 (Mith the UCS feature)* 3203* 3211* 3262* and 4245 
printers* the UCS image can be displayed on the printer for 
visual verification using either of the folloMing parameters! 

• In JCL: UCS=( character set code » .VERIFY) 

• In the SETPRT macros UCS=( character set code »fV) 

The verification display header appears in the format shown 
beloM. 



UCS IMAGE VERIFICATION image id CFOLDl [ description ] 



image id 

The 1- to 4-character name of the UCS image. 

description 

The descriptive information supplied for this UCS image in 
the UCS image table. 

The 4245 also* optionally* prints the image. 

See JCL and Data Management Macro Instructions for more 
information on the UCS VERIFY parameters. 



O 
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EXAMPLES OF ADDING TO THE UCS IMAGE TABLE 



Example 1: Adding a New Band ID to the 4245 Image Table (UCS5) 

In this example* the band name RPQl Nith description "RPQ BAND" 
is added to UCS5. In the UCS verification display, 7 lines of 
50 characters each are printed. Macro IGGUCS5 causes the UCS 
image table source (as distributed by IBM) to be included. 





72 


//UCS5 


JOB ... 


// 


EXEC ASMFCL, 


// 


PARM.ASM=»NODECK,LOAD' , 


// 


PARM.LKED='OL, RENT, REUS' 


//SYSPRINT DD SYSOUT=A I 


//ASM. 


5YSIN DD K 




TITLE 'UPDATED UCS5 IMAGE TABLE' 


UCS5 


CSECT 




IGGUCSIT NAME=RPQ1, X 




VLENGTH=(50,50,50,50,50,50,50), X 




DESCR='RPQ BAND' 




IGGUCS5 




END 


/x 




//LKED 


.SYSLMOD DD DSN=SYS1 . IMAGELIB(UCS5) ,DISP=OLD, 


// 


SPACE= (OVERRIDE SECONDARY ALLOCATION) 






Notes to Example 1: 

1. The RENT and REUS linkage editor attributes are used for 
performance considerations in a paging environment. They 
may be omitted. 

2. Executing the ASMFCL procedure does not actually generate 
executable code. The assembler/linkage editor is used to 
place the UCS image table entry into SYSl . IMAGELIB. 

3. The SPACE parameter is overridden here because the ASMFCL 
cataloged procedure has secondary allocation specified. 
Elimination of the override causes the original secondary 
allocation amount to be used. 



ADDING AN FCB IMAGE TO THE IMAGE LIBRARY 



Tmo standard FCB images, STDl and STD2, are included in 
SYSl .IMAGELIB during system generation for the follouiing 
printers^ 

3203 

3211 

4245 

STDl sets line spacing at 6 lines per inch for an 8-1/2 inch 
form; STD2 is a default FCB image that sets line spacing at 6 
lines per inch for an 11-inch form. Channels for both images 
are evenly spaced, Mith Channel 1 on the fourth line and Channel 
9 on the last line. See Figure 44 and Figure 45 on page 178.2 
for sample STDl and STD2 images. 

The 4245 printer loads a default FCB image into the buffer at 
pouiei — on time. The 4245 default FCB image is an 11-inch form 
with 6 lines per inch and a Channel 1 on the first print line. 
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The lEBIMAGE utility should be used to create and modify FCB 
modules for the 3800 printing subsystem. 



J 



FCB2STD1 CSECT 










DC 


X»80' 


DEFAULT 




DC 


AL1(51) 


FCB IMAGE LENGTH = 51 


DC 


X»000000' 


LINE 


1, 


2, 3 


DC 


X'Ol' 


LINE 


4, 


CHANNEL 1 


DC 


X'OOOOOO' 


LINE 


5, 


6, 7 


DC 


X»02' 


LINE 


8, 


CHANNEL 2 


DC 


X'000000» 


LINE 


9, 


10, 11 


DC 


X'03» 


LINE 


12, 


CHANNEL 3 


DC 


X'OOOOOO' 


LINE 


13, 


14, 15 


DC 


X»04» 


LINE 


16, 


CHANNEL 4 


DC 


X'000000» 


LINE 


17, 


18, 19 


DC 


X'05' 


LINE 


20, 


CHANNEL 5 


DC 


X'OOOOOO* 


LINE 


21, 


22, 23 


DC 


X»06' 


LINE 


24, 


CHANNEL 6 


DC 


X»000000' 


LINE 


25, 


26, 27 


DC 


X»07» 


LINE 


28, 


CHANNEL 7 


DC 


X'OOOOOO' 


LINE 


29, 


30, 31 


DC 


X'08» 


LINE 


32, 


CHANNEL 8 


DC 


X'000000» 


LINE 


33, 


34, 35 


DC 


X'OA* 


LINE 


36, 


CHANNEL 10 


DC 


X»000000' 


LINE 


37, 


38, 39 


DC 


X'OB' 


LINE 


40, 


CHANNEL 11 


DC 


X'OOOOOOOOOOOOOOOO* 


LINE 


41, 


42, 43, 44, 


DC 


X»OC' 


LINE 


49, 


CHANNEL 12 


DC 


X»00» 


LINE 


50 




DC 


X'19' 


LINE 


51, 


CHANNEL 9-EN 


END 











Figure 44. Sample of the Standard FCB Image STDl 



45, 46, 47, 48 



9-END OF FCB IMAGE 






FCB2STD2 CSECT 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
END 



X»80' 
AL1(66 



*0000 

'01' 

'0000 

'02' 

'0000 

»03' 

'0000 

*04' 

'0000 

'05' 

'0000 

'06' 

>0000 

'07' 

'0000 

'08' 

'0000 

'OA' 

'0000 

'OB' 

'0000 

'OC 

'00» 

'19' 



) 

00' 

000000' 
000000' 
000000' 
000000' 
000000* 
000000' 
000000' 
000000' 
000000* 
000000' 



DEFAULT 






FCB IMAGE LENGTH 


= 66 


LINE 


1, 


2, 3 




LINE 


4, 


CHANNEL ; 


. 


LINE 


5, 


6, 7, 8, 


9 


LINE 


10, 


CHANNEL 


2 


LINE 


11, 


12, 13, 


14, 


LINE 


16, 


CHANNEL 


3 


LINE 


17, 


18, 19, 


20, 


LINE 


22, 


CHANNEL 


4 


LINE 


23, 


24, 25, 


26, 


LINE 


28, 


CHANNEL 


5 


LINE 


29, 


30, 31, 


32, 


LINE 


34, 


CHANNEL 


6 


LINE 


35, 


36, 37, 


38, 


LINE 


40, 


CHANNEL 


7 


LINE 


41, 


42, 43, 


44, 


LINE 


46, 


CHANNEL 


8 


LINE 


47, 


48, 49, 


50, 


LINE 


52, 


CHANNEL 


10 


LINE 


53, 


54, 55, 


56, 


LINE 


58, 


CHANNEL 


11 


LINE 


59, 


60, 61, 


62, 


LINE 


64, 


CHANNEL 


12 


LINE 


65 






LINE 


66, 


CHANNEL 


9-EN 



15 
21 
27 
33 
39 
45 
51 
57 



63 



9-END OF FCB IMAGE 



Figure 45. Sample of the Standard FCB Image STD2 






178.2 MVS/370 System Programming Library? Data Management 



You may add a 3211 format FCB image to those that reside in 
SYSl. IMAGELIB* using the assembler and linkage editor. No 
executable code is generated; the assembler prepares DCs» and 
the linkage editor puts them into SYSl.IMAGELIB. The neu FCB 
image must be structured according to the following rules! 

1. The member name cannot exceed 8 bytes. The first 4 
characters of the name must be FCB2. The characters that 
follow identify the FCB image and are referred to as the 
"image identifier" (ID). Any combination of valid assembler 
language characters can be used» with the exception of a 
single "C" or "U"» because these are used by the system to 
recognize special conditions. The image identifier must be 
specified in the FCB keyword of a DD statement or in the 
SETPRT macro to load the image into the FCB buffer. 

2. The first byte of the FCB load module specifies whether the 
image is a default. (Default images may be used by the 
system for jobs that do not request a specific image.) 
Specify the following in the first byte! 



4. 



^p'^, 



X»80' 
X»00» 



indicates a default image 
indicates a nondefault image 



The second byte of the load module indicates the number of 
bytes to be transferred to the control unit to load the FCB 
image. This count includes the byte* if used» for the print 
position indexing feature. 

The third byte of the load module (the first byte of the FCB 
image) is either the print position indexing byte» or the 
li nes-per-inch byte. The print position indexing byte is 
optional and* when used» precedes the li nes-per-inch byte. 
The 4245 printer accepts and discards the index byte if it 
is present* because the printer does not support the 
indexing feature. A description of the print position 
indexing feature and its use will be found in IBM 5211 
Printer* 3216 Interchangeable Train Cartridge* and 3811 
Printer Control Unit Component Description and Operator's 
Guide. 



The special index flag in the third byte contains X*80* plus 
a binary index value* from 1 to 32 (the default is 1). This 
index value sets the left margin: l indicates flush-left* 
any other value indicates a line indented that many spaces. 

The form image begins with the li nes-per-inch (LPI) byte. 
The LPI byte defines the number of lines per inch (6 or 8) 
and also represents the first line of the page. It may or 
may not also contain a channel identifier. 

Typically* the length of an FCB image is consistent with the 
length of the form it represents. For example* an 8-1/2 
inch form to be printed at 6 LPI has an FCB image that is 51 
bytes long (8-1/2 inches times 6 LPI). 

The LPI byte appears as follows: 

X'ln» sets 8 LPI 

X'Onr sets 6 LPI 

5. All remaining bytes (lines) must contain X*On'» except the 
last byte* which must be X'ln*. The letter n can be a 
hexadecimal value from 1 to C* representing a channel (one 
to 12)* or it can be 0* which means no channel is indicated. 

In Figure 46 on page 178.4* an FCB load module is assembled and 
added to SYSl.IMAGELIB. The image defines a print density of 8 
lines per inch on an 11-inch form* with a right shift of 15 line 
character positions (1-1/2 inches). 
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//ADDFCB 

//STEP 

// 

//ASM.SYSIN 

FCB2ID1 

XTHIS EXAMPLE 



JOB MSGLEVEL=1 

EXEC PR0C=ASMFCL,PARM.ASM=»NODECK,LOAD», 

PARM.LKED=' LIST, OL,REFR, RENT, XREF» 
DD X 
CSECT 
IS FOR A FORM LENGTH OF 11 INCHES WITH 8 LPI (88 LINES) 



/X 

//LKED.SYSLMOD 

// 



DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
END 

DD 



X»80» 

AL1(89) 

X'8F» 

X»10' 

XL4»0 

X'Ol' 

XL6'0 

X»02' 

XL6*0 

X»03' 

XL6'0 

X'04» 

XL6»0 

X»05» 

XL6'0 

X»06» 

XL6»0 

X'07» 

XL6»0 

X»08» 

XL6'0 

X»09» 

XL6'0 

X»OA» 

XL6»0 

X'OB» 

XL6'0 

X'OC 

XL4'0 

X'10» 



THIS IS A DEFAULT IMAGE 
LENGTH OF FCB IMAGE AND 
OFFSET 15 CHARACTERS TO 
8 LINES PER INCH-NO CHANNEL FOR 
4 LINES NO CHANNEL 

1 IN LINE 6 
NO CHANNEL 

2 IN LINE 13 
6 LINES NO CHANNEL 
CHANNEL 3 IN LINE 20 
6 LINES NO CHANNEL 
CHANNEL 4 IN LINE 27 
6 LINES NO CHANNEL 



INDEXING BYTE 
THE RIGHT 

LINE 1 



CHANNEL 
6 LINES 
CHANNEL 



CHANNEL 
6 LINES 
CHANNEL 



5 IN LINE 34 
NO CHANNEL 

6 IN LINE 41 



6 LINES NO CHANNEL 
CHANNEL 7 IN LINE 48 
6 LINES NO CHANNEL 
CHANNEL 8 IN LINE 55 
6 LINES NO CHANNEL 

9 IN^ LINE 62 
NO CHANNEL 



CHANNEL 
6 LINES 
CHANNEL 
6 LINES 
CHANNEL 
6 LINES 
CHANNEL 
4 LINES 



10 
NO 
11 
NO 
12 
NO 



IN LINE 69 
CHANNEL 
IN LINE 76 
CHANNEL 
IN LINE 83 
CHANNEL 



POSITION 88 LAST LINE IN IMAGE 






DSNAME=SYS1.IMAGELIB(FCB2ID1),DISP=0LD, 
SPACE= (OVERRIDE SECONDARY ALLOCATION) 



Figure 46. Sample Code to Assemble and Add an FCB Load Module to SYSl .IMAGELIB 



Notes to Figure 46: 

1. The RENT and REFR linkage editor attributes are used for 
performance considerations in a paging environment. They 
may be omitted. 

2. Executing the ASMFCL procedure does not actually generate 
executable code. The assembler/linkage editor is used to 
place the FCB image into SYSl. IMAGELIB, 

3. The SPACE parameter is overridden here because the ASMFCL 
cataloged procedure has secondary allocation specified. 
Elimination of the override causes the original secondary 
allocation amount to be used. 



RETRIEVING AN FCB IMAGE FROM SYSl. IMAGELIB 



If you Mant to modify an FCB image in virtual storage before 
loading it Into a forms control buffer, you can use this 
sequence of macro instructions to read the FCB image into 
virtual storage. 
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1. An IMGLIB macro instruction^ Mith the OPEN parameter 

2. A BLDL macro instruction^ to determine whether the FCB image 
you Mant is in the image library 

3. A LOAD macro instruction* to load the image into virtual 
storage 

After the image has been read in» you should issue the IMGLIB 
macro instruction Mith the CLOSE parameter and the address of 
the DCB that was built by the first IMGLIB macro. A SETPRT 
macro instruction can be used to load the forms control buffer 
with the modified image. Printers other than the 3800 will 
require the use of an FCB entry in an exit list* as described in 
Data Management Services . 

The format of the BLDL and SETPRT macros is given in Data 
Management Macro Instructions ; the format of the LOAD macro is 
given in Supervisor Services and Macro Instructions . 

The format of the IMGLIB macro is shown below: 



[symbol] 


IMGLIB 


COPENlCLOSE^addr} 



OPEN 



specifies that a DCB is to be built for SYSl . IMAGELIB and 
that SYSl. IMAGELIB is to be opened. The address of the DCB 
is returned in register 1. 



CLOSE 



specifies that SYSl. IMAGELIB is to be closed. 



addr 

specifies the RX-type address of the word which points to 
the DCB. If coded in the form (jreg)» then the register in 
parentheses contains the address of the DCB* not the 
address of the fullword. 

Return codes from the IMGLIB OPEN macro are shown below^ 



Return Code 


Meaning 


(00) 


Operation successful. 


4 (04) 


Either the volume containing 
SYSl. IMAGELIB is not mounted or a 
required catalog volume is not mounted. 


8 (08) 


Either SYSl .IMAGELIB does not exist on 
the volume to which the catalog points* 
or SYSl. IMAGELIB is not cataloged. 


12 (OC) 


An error occurred in reading the catalog 
or VTOC. 



BLDL and LOAD are the only macros that may refer to the DCB 
built by the IMGLIB macro. 
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CHAPTER 9. JES2 SUPPORT FOR THE IBM 1403* 3203 HODEL 5. AND 3211 PRINTERS 



UCS ALIAS NAMES 

The system assigns an alias for each installation-standard print 
chain not actually defined on a given printer. This provides 
JES2 Mith flexibility in scheduling printers for SYSOUT data 
sets. For example* a request for the 1403 TN train Mould be 
assigned the Til train* if the data set Mere printed on a 3211. 
The assigned alias names* Mhich folloM the naming conventions 
currently used in SYSl .IMAGELIB* are' 

IMAGE ALIAS 

UCSIAN UCSlAll 

UCSIHN UCSlHll 

UCSIPN UCSlPll 

UCSITN UCSlTll 

UCS2A11 UCS2AN 

UCS2H11 UCS2HN 

UCS2P11 UCS2PN,UCS2RN,UCS2QN 

UCS2T11 UCS2TN 

The image and alias names are included in SYSl.INAGELIB at 
system generation. 

Some trains* such as SN and Gil* do not have aliases because 

neither has an equivalent train on the other printer. An 

installation can assign an alias* if it so chooses. (See 

Linkage Editor and Loader for details about the ALIAS /f^ ^ 

statement.) If an alias is supplied* JES2 Mill use it. If an w j 

alias is not supplied* an installation-defined SYSOUT class or a ^>^ 

printer routing code (specified via the DEST parameter) should 

be used to assign the data set to the correct printer. If a 

SYSOUT class or a printer routing code is not used* and JES2 is 

directed to print a data set on a printer for Mhich the proper 

image is not supplied* JES2 notifies the operator. The operator 

can then print the data set Mith a valid train or redirect the 

data set to the proper printer via the *$E* command. 

If an installation defines a neM train* it can supply an alias 
name for that train* via the linkage editor ALIAS statement* 
Mhen including the image in SYSl.INAGELIB. 

THE 3211 INDEXING FEATURE 

JES2 supports the 3211 Indexing Feature in tMo Nays* 

1. Specification of the INDEX parameter on the /^OUTPUT card. 

2. The extended- FCB image! 

JES2 supplies tMO special FCBs* FCB26 for 6 lines per inch 
and FCB28 for 8 lines per inch (specified as FCB=6 and 
FCB=8* respectively). These FCBs contain a channel 1 
indication in position 1* a special index flag in the third 
byte* and the number of lines per inch in the fourth byte of 
the image. 

The special index flag in the third byte of FCB26 and FCB28 
contains X*80* plus a binary index value* in the range 1 to 
32 (default=l). The index value sets the left margin (1 
indicates flush-left position* other values cause 
indentation of the print line by N-1 positions). 
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If any other FCB images are to be used by JES2» they must 
specify channel 1 in position 1; otherMise JES2 incorrectly 
positions the forms in the printer. (STDl and STD2 do not 
specify channel 1 in position 1 and therefore must not be 
specif ied> unless altered^ for JES2.) 

If the third byte of any other FCB image contains a data 
character (specifying the number of lines per inch) other 
than X*80'» JES2 uses that specification and supplies an 
index value of 1. 



ygW ?20? WOPPH g PRIHTPR 



The IBM 3203 Model 5 Printer is treated the same as a 3211 
printer by JES2» except that the 3203 Model 5 does not support 
the 3211 indexing feature* and any indexing commands from JES2 
are ignored by the 3203 Model 5. The 3203 Model 5 uses 3211 FCB 
images and its ouin unique UCS images. UCS images etre listed in 
System Generation Reference . 



o 
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CHAPTER 10. CATALOG, SCRATCH, AND RENAME DUHMY HODULES 



The load modules for CATALOG (SVC 26), SCRATCH (SVC 29), and 
RENAME (SVC 30) contain as their entry points the dummy modules 
1GG026DU, IGG029DU, and IGG030DU, respectively. These dummy 
modules immediately pass control to the first processing module 
for their respective SVCs without performing any processing 
themselves. The CATALOG dummy module IGG026DU receives control 
from SVC 26 and immediately passes control to module IGC0002F. 
The SCRATCH dummy module 1GG029DU receives control from SVC 29 
and immediately passes control to module IGC0002I. The RENAME 
dummy module, IGG030DU, receives control from SVC 30 and 
immediately passes control to IGC00030. 

The load module for SCRATCH(SVC29) also contains the dummy 
module IGG029DM. The SCRATCH dummy module IGG029DM receives 
control from IGG0290D when an error return code of ^ or 8 is 
indicated, and immediately passes control to the location 
pointed to by register 14. 

If you require special processing either before or after SVC 26, 

29, or 30, you replace the appropriate dummy module(s) with your 

own module(s). Your replacement modules must follow all the 

characteristics and programming conventions for SVC routines. 

For information on writing SVC routines, characteristics of SVC 

routines, programming conventions for SVC routines, and 

inserting SVC routines, see System Programming Library? 

Supervisor Services and Macro Instructions . Your modules may 

replace IGG026DU, IGG029DU, IGG029DM, and IGG030DU in SYSl.AOSDO 

prior to system generation, or you may replace the dummy modules 

in SYSl.LPALIB after system generation. Information on how to 

replace the dummy modules with your modules can be obtained from 

the appropriate link-edit step of the STAGE I system generation 

output. You may also obtain link-edit information from the '^^ 

STAGE I system generation macro SGIEC4DM in SYSl . AGENLIB . You 

may apply RTFs to CATALOG, SCRATCH, or RENAME with SMP without 

modifying your own versions of IGG026DU, IGG029DU, IGG029DM,and 

IGG030DU. 

The prolog of each of the dummy modules contains register 
conventions and other information about these modules. 



■>^ 
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CHAPTER 11. SPECIFYING BUFFER NUMBERS FOR PASD DATA SETS 



The BUFNO keyMord in the DCB macro and the BUFNO subparameter of 
the DCB keyword in the DD statement determine hou many buffers 
are allocated uihen accessing a partitioned or sequential data 
set using QSAM. The NCP keyword in the DCB macro determines how 
many un-CHECKed READ or UIRITE macro instructions are allowed 
when accessing a sequential or partitioned data set using BSAM; 
one buffer is used for each READ or URITE macro instruction. 

The sequential access method can construct a channel program to 
transfer up to 30 buffers or 240^000 bytes of data» whichever is 
less. If BUFNO or NCP is less than 30, no more than that number 
of buffers can be transferred with a single channel program. 

BUFNO is defaulted in OPEN to 5 if it is not specified for a 
QSAM DCB; NCP is defaulted to 1 in OPEN if it is not specified. 
The QSAM access method manages buffers. The user program must 
manage buffers when it uses BSAM. 



PERFORMANCE CONSIDERATIONS 



jr*\^ 



Buffer number and block size influence the rate with which data 
can be transferred and the operating system overhead per block. 
The use of more buffers reduces iper block transferred) the EXCP 
and lOS overhead and the time waiting for the DASD device to 
seek to the requested cylinder and rotate to the requested 
record (device latency time). However, if more buffers are 
allocated than a program can effectively process, the virtual 
pages containing those buffers will be paged out, effectively 
adding to the system overhead for the job. A large number of 
buffers also cause a large amount of real storage to be 
allocated to the job while the data is being transferred. 

A job in a low-performance group may get swapped out more 
frequently than a higher priority job. The number of buffers 
allocated for the job contributes to the number of pages which 
have to be swapped out. 

Programs that access data sets with small block size (for 
example, 80) can easily make effective use of 30 buffers which 
fit in, at most, two ^096-byte pages. The advantage of 30 
buffers over the default of five buffers is greats one channel 
program versus six channel programs to transfer 30 blocks. 

At the other end of the spectrum, usage of data sets with large 
blocking factors such as full-track blocking on 3350 or 
half-track blocking on 3380 can still be effective when only 3 
or 4 buffers, rather than 5 or more, are specified. The 
slightly lower DASD performance and small increase in EXCP and 
lOS instruction costs should be more than offset by a reduction 
in paging or swapping in a constrained environment. 

It can be seen that proper selection of buffer number can have a 
positive effect on the elapsed time of a job and the system 
overhead associated with the job. The DCB OPEN installation 
exit can use installation criteria for a default buffer number 
for QSAM DCBs (see "DCB Open Installation Exit" on page 125 for 
a description of the open installation exit). The NCP field of 
the DCB must be set by the program for BSAM DCBs. 
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APPENDIX A. VTOC ACCESS HACROS 



CVAFDIR HACRO 



SYNTAX 






IlabQll 


CVAFDIR 


ACCESS=READ|URITE|RLSE 

[,DSN=addr] 

I,BUFLIST=addr3 

t,VERIFY=YES|NOl / 

I,DEB=addr|UCB=a<^drl 

I , IOAREA=KEEP | (KEEP, addr )NOKEEP | 

(NOKEEP,addr)I 
t,HAPRCDS=YES |( YES, addr )|N0| 

(NO,addr)l 
[,IXRCDS=KEEP| ( KEEP, addr )|HOj^IIP| 

(NOKEEP,dddr)] 
[,BRANCH=YESMNO|(YES,SUP)|(YES,PGN)] 
[,riF=I|L|(E,addr)] 



1 The default is SUP if YES is coded. 

access: READ OR URITE A DSCB OR VIR(S), OR RELEASE BUFFER LISTS 

Uhen ACCESS is READ or URITE» a single DSCB is accessed for at\ 
indexed or nonindexed VTOC» or one or more VIRs are accessed for 
an indexed VTOC. 

ACCESS=READ 

Specifies that a single DSCB or one or more VIR(s) Brei to 
be read into a buffer Mhose address is in a buffer list. 

If the buffer list if for a DSCB> only one entry is used in 
the buffer list. The first entry with the skip bit set to 
zero and with a nonzero buffer address is used. 

All VIR(s) Mhose buffer list entry has the skip bit off 
Mill be read into a buffer. 

DSN and BUFLIST are required if ACCESS=READ for a DSCB 
buffer list. 

ACCESS=URITE 

Specifies that a single DSCB or one or more VIRs are to be 
Mritten from buffer(s) Mhose address is in a buffer list. 

URITE is permitted Mith BRANCHING only if the caller is 
authorized by APF. 

DSN and BUFLIST are required if ACCESS=URITE for a DSCB 
buffer list. 



If any buffer list entry has its modified bit set, only 
those entries Mith the modified bit set Mill be Mritten. 
no modify bits &rei on» all VIRs Mill be Mritten. 



If 



ACCESS=RLSE 

Applies only to VIR buffer lists. It requests the release 
of one or more buffers in the VIR buffer list chain 
identified in the BUFLIST keyMord, and the release of each 
buffer list for Mhich all buffers are released. 

DSN and BUFLIST are not required if ACCESS=RLSE. 



X^ 
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Only buffers in the buffer list with the skip bit set to 
zero and with a nonzero buffer address are released. The 
buffer list is not released if any entry has the skip bit 
set to one. 

For an indexed VTOC, if ACCESS=RLSE is coded, buffer lists 
and buffers pointed to by the BUFLIST keyword will be 
released* as well as buffer lists supplied in the CVAF 
parameter list CVMRCDS and CVIRCDS fields. If the CVMRCDS 
or the CVIRCDS buffers are supplied in the BUFLIST field, 
either directly or indirectly through chaining, the keyword 
MAPRCDS=YES, IXRCDS=KEEP, or MAPRCDS=(NO, 0) , 
IXRCDS=(NOKEEP,0) must be coded to prevent CVAF from 
freeing the buffers more than once. If buffers are 
released, the CVAF parameter list field pointing to the 
buffer list will be updated. 



DSN: specify THE NAME OF THE DSCB 



DSN= addr 

DSN specifies the address of a 44-byte data set name of the 
DSCB to be accessed. 

DSN is required if ACCESS=READ or URITE and the request is 
to read or write a DSCB. If a 140-byte DSCB is specified, 
the validity of the storage location is checked but its 
contents are ignored. 



BUFLIST : SPECIFY ONE OR MORE BUFFER LISTS 



BUFLIST= addr 

The BUFLIST keyword contains the address of a buffer list 
used to read or write a DSCB or VIRs. 






VERIFY: VERIFY THAT A DSCB IS A FORNAT-0 DSCB 



VERIFY=YES 

CVAF will verify that the DSCB i s a format-0 DSCB before 
writing the DSCB. The first four bytes of the key will bje 
compared with binary zeros. If the key does not start with 
four bytes of zeros, the DSCB will not be written and an 
error code will be returned. 

VERIFY=NO 

CVAF will not test the key of the DSCB. 

Note: VERIFY applies only when writing a 140-byte DSCB. VERIFY 
is ignored when a VIR is written. 



branch: specify THE ENTRY TO THE NACRO 



BRANCH=(YES>SUP) 

Requests that the branch entry to CVAFDIR be used. You 
must be in supervisor state. Protect key checking is 
bypassed. 

An 18-word save area must be supplied if BRANCH=YES is 
coded. No lock may be held on entry to CVAF. SRB mode is 
not allowed. 

BRANCH=YES 

Equivalent to BRANCH=(YES,SUP), because SUP is the default 
when YES is coded. Protect key checking is bypassed. 

BRANCH=(YES,PGM) 

Requests the branch entry. You must be authorized by APF 
and be in problem state. Protect key checking is bypassed. 
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BRANCH=NO 

Requests the SVC entry. You must be authorized by APF if 
any output operations are requested. Protect key checking 



, ,.... f\ 

is performed. \^ 



DEBIUCB: specify THE VTOC TO BE ACCESSED 

DEB= addr 

Supplies the address of a DEB opened to the VTOC to be 
accessed. CVAF Mill not alloM output requests to the VTOC 
or VTOC index if DEB i s supplied. No asynchronous requests 
may be performed by an unauthorized caller against the DEB 
(such as EXCP, CLOSEf EOV)» because CVAF Mill remove the 
DEB from the DEB table for the duration of the CVAF call. 
An unauthorized caller (neither APF authorized nor in a 
system key) must supply a DEB and not a UCB to CVAF. The 
unauthorized caller's DEB must have been created under the 
current task by either SAM or EXCP. 

UCB= addr 

Supplies the address of the UCB for the unit Mhose VTOC is 
to be accessed. An unauthorized caller must not use this 
parameter. 

If the address of a previously obtained I/O area is supplied 
through the lOAREA keyMord» neither UCB nor DEB need be 
supplied. OtherMise^ either a UCB or DEB must be supplied. If 
a UCB address is supplied^ it Mill be overlaid in the CVPL by 
the UCB address present in the I/O area. 

If DEB and UCB are supplied in the CVPL» the DEB address Mill be 
used and the UCB address Mill be overlaid in the CVPL by the UCB 
address in the DEB. 

ZOAREA: keep OR FREE THE I/O UORKAREA f 

IOAREA=KEEP 

Specifies the CVAF I/O area associated Mith the CVAF 
parameter list is to be kept upon completion of the CVAF 
request. IOAREA=KEEP may be coded Mith BRANCH=NO only if 
the caller is authorized (APF» or system key). 

If IOAREA=KEEP is coded» the caller must issue CVAF Mith 
I0AREA=NOKEEP specified at some future time» Mhether or not 
any further VTOC access is required^ for example* the 
recovery routine of the caller of CVAF. 

Coding IOAREA=KEEP alloMS subsequent CVAF requests to be 
more efficient* as certain initialization functions can be 
bypassed. Neither DEB nor UCB need be specified Mhen a 
previously obtained CVAF I/O area is supplied; neither can 
they be changed. 

When IOAREA=KEEP is first issued, CVAF returns the CVAF I/O 
area in the CVAF parameter list (CVIOAR). Subsequent calls 
of CVAF may use that same parameter list* and CVAF Mill 
obtain its I/O area from the CVIOAR. 

Mhen processing on the current volume is finished* release 
all areas that Mere kept. 

IOAREA=(KEEP»addr) 

Provides the address of a previously obtained I/O area. If 
a different CVAF parameter list is used* the previously 
obtained I/O area may be passed to CVAF by coding its 
address as the second parameter of the lOAREA keyMord. 

IOAREA=NOKEEP ^ y 

Causes the Mork area to be freed upon completion of the m ] 
CVAF request. ^^ 
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XOAREA=(NOKEEPfSddr) 

Causes a previously obtained work hras to be freed upon 
completion of the CVAF request. 
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NF: specify THE FORM OF THE MACRO 






This keyMord specifies Mhether the list» execute^ or normal form 
of the macro is requested. 

MF=I 

If I i s coded» or neither L nor E is coded» the CVAF 
parameter list is generated and CVAF is called. This is 
the normal form of the macro. 

L indicates the list form of the macro. A parameter list 
is generated^ but CVAF is not called. 

MF=(E,ad[dr) 

E indicates the execute form of the macro. The CVAF 
parameter list Mhose address is in *addr' can be modified 
by this form of the macro. 



MF=L 



HAPRCDS: KEEP OR FREE MAPRCDS BUFFER LIST AND BUFFERS 



This keyword applies to an indexed VTOC only and specifies the 
disposition of the MAPRCDS buffer list and buffers. 

MAPRCDS=YES 

Specifies that the buffer list and buffers are to be 
retained at the end of processing. 

If no buffer list address is in the CVAF parameter list» 
CVAF will read the MAP VIRs into buffers it obtains. The 
buffer list that contains the address and RBAs of the VIRs 
can be accessed after processing from the CVAF parameter 
list field, CVMRCDS. The buffer list and VIR buffers are 
in your protect key J subpool if you are not authorized; 
229 if you are. 

Uhen processing on the current volume is finished, release 
all areas that were kept. 

MAPRCDS=(YES,addr) 

If YES is coded and the buffer list address (CVMRCDS in 
CVAF parameter list) is supplied, VIRs are not read. 

The CVMRCDS buffer list used in CVAFDIR macro can be passed 
to another CVAF macro call through the MAPRCDS keyword. 

If MAPRCDS=YES is coded for an unindexed VTOC, the function 
is performed, but an error code will be returned. 

MAPRCPS=NO 

If MAPRCDS=NO is coded, all the buffers without the skip 
bit on in the buffer list whose address is in the CVMRCDS 
field of the CVPL will be freed. If all the buffers are 
freed, the buffer list will also be freed. 

HAPRCDS =( NO »add£) 

Causes buffer lists and buffers previously obtained by CVAF 
to be freed. 

You must free buffer lists and buffers obtained by CVAF. This 
can be done in three ways* 

• By coding MAPRCDS=NO on the CVAFDIR macro that obtained the 
buffers 

• By coding MAPRCDS=NO on a subsequent CVAF macro 

• By coding CVAFDIR ACCESS=RLSE and providing the address of 
the buffer list in the BUFLIST keyword 

Note: To maintain the integrity of MAP records read, you must 
enqueue the VTOC and reserve the unit. 
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c 



XXRCDS: RETAIN VZERS XN VIRTUAL STORAGE 

This keyMord applies to indexed VTOCs only. 

IXRCDS=KEEP 

Specifies that VIERs read into storage ore to be kept in 
virtual storage. The VIERs &re retained even if processing 
cannot complete successfully. The CVAF parameter list in 
field CVIRCDS Mill have the address of a buffer list 
containing the VIR buffer addresses and RBAs of the VIERs 
read. 

Index search function Mill dynamically update the buffer 
list andf Mhen necessary* obtain additional buffer lists 
and chain them together. 

If KEEP is specified and no buffer list is supplied to CVAF 
in the CVPL* CVAF Hill obtain a buffer list and buffers and 
read the first high-level VIER. The address of the buffer 
list is placed in the CVMICDS field of the CVPL. The first 
high-level VIER Mill be checked for Ihe VXFHLV bit and to 
see if the VXVISE bit is off. 

The buffer list and VIR buffers ore in your protect key. 
The subpool is if you are not authorized; subpool 229 if 
you are. 

If IXRCDS=KEEP is coded for an nonindexed VTOC, a request 
to read or Hrite a DSCB Mill be performed* but an error 
code Mill be returned. 

When processing on the current volume is finished* release 
all areas that Mere kept. 

IXRCDS=(KEEP>addr] 

The index records buffer list address from one CVAF request 

is being passed to this CVAF parameter list by specifying 

its address as the second parameter in the IXRCDS keyMord. \j^' 

IXR0P^=NOKEEP 

If NOKEEP is coded* the VIERs that are accessed (if any) 
are not retained. Furthermore* the buffer list supplied in 
the CVIRCDS field in the CVAF parameter list is released* 
as are all buffers found in the buffer list. If the skip 
bit is set in any entry in the buffer list* the buffer and 
buffer list Mill not be freed. 

IXRCDS=CNOKEEP>sMr) 

Specifies that previously accessed VIERs are not to be 
retained. 

You must free buffer lists and buffers obtained by CVAF. This 
can be done in three Mays* 

• By coding IXRCDS=NOKEEP on the CVAFDIR macro that obtained 
the buffers 

• By coding IXRCDS=NOKEEP on a subsequent CVAF macro 

• By coding CVAFDIR ACCESS=RLSE and providing the address of 
the buffer list in the BUFLIST keynord 

Note: To maintain the integrity of the VIERs read* you must 
enqueue the VTOC and reserve the unit. 



,/f 
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CVAFDSM MACRO 



SYNTAX 



Cjabell 


CVAFDSM 


ACCESS=MAPDATA 

, MAP=INDEX 1 VOLUME | VTOC 

I,EXTENTS=addr] 

[,MAPRCDS=YES^ I ( YES,addr ) INO^ 1 

(NO,addr)] 
C>UCB=addrlDEB=addr] 
[,COUNT=YES|NO] 
[,CTAREA=addr] 
[ , IOAREA=KEEP I (KEEP>addr ) INOKEEP | 

(NOKEEP,addr)] 
[ , BRANCH=NO | YES ^ | ( YES , SUP ) I ( YES > PGM ) ] 
[,MF=I|L|(E,addr)] 



^Default if MF=I. 

^Default if MF=L or MF=(E,addr). 

'Default is SUP if YES is coded. 

ACCESS=MAPDATA: REQUEST INFORMATION FROM THE INDEX SPACE MAPS 

ACCESS=MAPDATA 

Obtains data from the index space maps, 
data are available: 



Three kinds of 






The number of format-0 DSCBs (the data is obtained from 
the VTOC map of DSCBs) 

The number of unallocated VIRs in the index (the data 
is obtained from the VTOC index map) 

The number (and location) of extents of unallocated 
pack space (the data is obtained from the VTOC pack 
space map) 



MAPRCDS: KEEP OR FREE MAPRCDS BUFFER LIST AND BUFFERS 



o 

^||k|||||r 



MAPRCDS=YES 

Specifies that the buffer list and buffers are to be 
retained at the end of the function. 

If YES is specified and no buffer list is supplied through 
the CVAF parameter list» CVAF will read the MAP VIRs into 
buffers obtained by CVAF. The buffer list that contains 
the address and RBAs of the VIRs can be accessed after the 
CVAF call from the CVAF parameter list field, CVMRCDS. The 
buffer list and VIR buffers are in the caller's protect 
key* subpool if the caller is not authorized; subpool 
229, if the caller is authorized. 

YES is the default if MF=I is specified or defaulted. 

t4hen processing on the current volume is finished, release 
all areas that Mere kept. 

MAPRCDS= ( YES , addr ) 

If YES is coded but the buffer list address (CVMRCDS in 
CVAF parameter list) is supplied, the VIRs are not read. 

The CVMRCDS buffer list from one CVAF call can be passed to 
another CVAF macro call through the MAPRCDS keyword. 
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NAPRCDS=NO 

If MAPRCDS=NO is codedt the MAP records buffers and buffer ^-^ 
list will be freed upon completion of the CVAFDSM function. /f \ 



NO i s the default if MF=L is specified. 

MAPRCDS=(NO,addr) 

Causes buffer lists and buffers previously obtained by CVAF 
to be freed. 

Buffer lists and buffers obtained by CVAF must be freed by the 
caller. This can be done' in three Mays: 

• By coding MAPRCDS=NO on the call that obtained the buffers 

• By coding MAPRCDS=NO on a subsequent CVAF call 

• By calling CVAFDIR ACCESS=RLSE and providing the buffer list 
in the BUFLIST keyword 

If MF=(E»addr) is coded and MAPRCDS is not coded* the 
parameter list value of MAPRCDS is not changed. 

Note: To maintain the integrity of the MAP records read» you 
must enqueue the VTOC and reserve the unit. 



map: identify THE NAP TO BE ACCESSED 



extents: identify HHERE EXTENTS FROM THE VPSN ARE RETURNED 



EXTENTS=addr 

If one or more extents from the VPSM are requested* EXTENTS 
is the address of a 1-byte count field containing the 
number of 5-byte extents that follow. In the first two 
bytes of the first 5-byte extent* you must supply the 
relative track address (RTA) at which CVAF should start the 
VPSM search. The first extent area is updated with 
information on the next free extent found that has a higher 
starting RTA than that supplied. Each subsequent extent 
area is filled in with information on free space extents 
(in ascending track address order). 

Information on free extents has the format* XXYYZ* where: 

• XX i s the relative track address of the first track of 
the extent. 

• YY i s the number of whole cylinders in the extent. 

• Z is the number of additional tracks in the extent. 

Only XX is supplied by the caller in the first extent area. 
CVAF will start searching the VPSM at relative track 
address XX. 



o 



NAP=INDEX 

Specifies the VTOC index map (VIXM) is to be accessed and a 
count of unallocated VIRs returned. COUNT=YES must also be 
coded. 

riAP=VOLUME 

Specifies the VTOC pack space map (VPSM) is to be accessed 

and information on unallocated extents of pack space 

returned. EXTENTS=addr and COUNT=NO must also be coded. ''%..J^' 

MAP=VTOC 

Specifies the VTOC map of DSCBs (VMDS) is to be accessed 
and a count of format-0 DSCBs returned. COUNT=YES must 
also be coded. 



,<'^' 
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If all the unallocated extents in the VPSM bvb provided 
before filling in all the supplied extent areas* the 
remaining extent areas are set to zero. Register 15 is set 
to 4 on return, with the CVSTAT field in the CVPL set to 
X*20* to indicate end of data. 
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debIucb: specify the vtoc to be accessed 






UCB= addr 

Supplies the address of the UCB for the unit Mhose VTOC is 
to be accessed. An unauthorized caller may not supply a 
UCB to CVAF. 

DEB= addr 

Supplies the address of a DEB opened to the VTOC to be 
accessed. CVAF Mill not alloM output requests to the VTOC 
or VTCC index if DEB is supplied. No asynchronous requests 
may be performed by an unauthorized caller against the DEB 
(such as EXCP» CLOSE» EOV)» because CVAF Mill remove the 
DEB from the DEB table for the duration of the CVAF call. 
An unauthorized caller (neither APF authorized nor in a 
system key) must supply a DEB and not a UCB to CVAF. The 
unauthorized caller's DEB must have been created under the 
current task by either SAM or EXCP. 

If a previously obtained CVAF I/O area is supplied through the 
lOAREA keyMordf neither UCB nor DEB need be supplied. 
OtherMise» either a UCB or DEB must be supplied. If a UCB 
address is supplied^ it Mill be overlaid in the CVPL Mith the 
UCB address in the I/O area. 

If DEB and UCB are supplied in the CVPL> the DEB Mill be used^ 
and the UCB address supplied Mill be overlaid in the CVPL Mith 
the UCB address obtained from the DEB. 

count: OBTAIN A COUNT OF UNALLOCATED DSCBS OR VI R5 

COUNT=YES 

Indicates a count of unallocated DSCBs or VIRs in the 
designated space map is requested. MAP=VTOC or MAP=INDEX 
must be specified if COUNT=YES is coded. 

COUNT =N0 

Indicates a count of unallocated DSCBs or VIRs is not 
desired but» rather^ information on free space on the pack 
is desired. MAP=VOLUME must be coded if COUNT=NO is coded 
or defaulted. 

CTAREA: SUPPLY A FIELD TO CONTAIN THE NUHBER OF FORMAT-0 DSCBS 

CTAREA=addr 

Gives the address of a 4-byte field to contain the number 
of format-0 DSCBs Mhen COUNT=YES, MAP=VTOC is specified; or 
the number of unallocated VIRs in the VTOC index Mhen 
COUNT=YES, MAP=INDEX is specified. 

IOAREA: keep OR FREE THE I/O UORK AREA 

IOAREA=KEEP 

Specifies the CVAF I/O area associated Mith the CVAF 
parameter list is to be kept upon completion of the CVAF 
request. IOAREA=KEEP may be coded Mith BRANCH=NO only if 
the caller is authorized (APF, or system key). 

If IOAREA=KEEP is coded, the caller must issue CVAF Mith 
IOAREA=NOKEEP specified at some future time, Mhether or not 
any further VTOC access is required: for example, the 
recovery routine of the caller of CVAF. 

Coding IOAREA=KEEP alloMs subsequent CVAF requests to be 
more efficient, as certain initialization functions can be 
bypassed. Neither DEB nor UCB need be specified Mhen a 
previously obtained CVAF I/O area is supplied; neither can 
they be changed. 

When IOAREA=KEEP is first issued, CVAF returns the CVAF I/O 
area in the CVAF parameter list (CVIOAR). Subsequent calls 
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of CVAF may use that same parameter list» and CVAF Mill 
obtain its I/O area from the CVIOAR. 

bihen processing on the current volume is finished^ release 
all areas that Mere kept. 

XOAREA=(KEEP»sddr) 

Provides the address of a previously obtained I/O area. If 
a different CVAF parameter list is used» the previously 
obtained CVAF I/O area may be passed to CVAF by coding its 
address as the second parameter of the lOAREA keyMord. 

IOAREA=NOKEEP 

Causes the Mork area to be freed upon completion of the 
CVAF request. 

ZOAREA=(NOKEEP,addr) 

Causes a previously obtained Mork area to be freed upon 
completion of the CVAF request. 



branch: SPECIFY THE ENTRY TO THE HACRO 



BRANCH=(YE8>SUP) 

Requests that the branch entry to CVAFDIR be used. The 
caller must be in supervisor state. Protect key checking 
is bypassed. 

An 18-Mord save area must be supplied if BRANCH=YES is 
coded. No lock may be held on entry to CVAF. 3RB mode is 
not alloMed. 

BRANCH^ YES 

Equivalent to BRANCH=(YES,SUP)» because SUP is the default 
Mhen YES is coded. Protect key checking is bypassed. 

BRANCH=(YES,PGH) (^ ^ 

Requests the branch entry. The caller must be APF \J^ 

authorized and in problem state. Protect key checking is 
bypassed. 

BRANCH=NO 

Requests the SVC entry. The caller must be APF authorized 
if any output operations are requested. Protect key 
checking is performed. 



HF: SPECIFY THE FORN OF THE HACRO 



This keyword specifies Mhether the list» execute^ or normal form 
of the macro i s requested. 



MF=I 



HF=L 



If I is coded> or neither L nor E is coded* the CVAF 
parameter list is generated as is code to call CVAF. This 
is the normal form of the macro. 

L indicates the list form of the macro. A parameter list 
is generated* but code to call CVAF is not generated. 



HF=(E,a4dr) 

E indicates the execute form of the macro. The remote CVAF 
parameter list supplied as 'addr* is used in» and can be 
modified by* the execute form of the macro. 
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CVAFSEQ MACRO 



SYNTAX 



ClabelJ 


CVAFSEQ 


ACCESS=GT|GTEQ 

[,BUFLIST=addr] 

[,DSN=addr] 

t,UCB=addr|DEB=addrl 

[, DSNONL Y=NOi YES] 

E,ARG=addr] 

[,IOAREA=KEEP|(KEEP»addr) INOKEEPI 

(NOKEEP>addr)] 
[ , IXRCDS=KEEP 1 (KEEPaddr ) | NOKEEP | 

(NOKEEP»addr)] 
[ , BRANCH=NO j YES M ( YES , SUP ) | ( YES > PGM ) ] 
[,MF=I|L|(E,addr)] 



^If YES, default is SUP. 



^**>^ 
\«^' 



access: specify relationship BETUEEN SUPPLIED AND RETURNED DSN 

ACCESS=GT 

Specifies that the DSN or argument value is to be used to 
return a DSCB whose DSN or argument is greater than that 
supplied. 

ACCESS=GTEQ 

Specifies that the DSN or argument value is to be used to 
return a DSCB Mhose DSN or argument is greater than or 
equal to that supplied. 

Note: A CVAF call specifying ACCESS=GTEQ should be 
followed by an ACCESS=GT request, or the same DSCB or name 
Mill be returned. 



BUFLIST: specify one or more buffer LISTS 

BUFLIST= addr 

The BUFLIST keyword supplies the address of a buffer list 
used to read or write DSCBs and VIRs. 

DSN: SPECIFY ACCESS BY DSN ORDER OR BY PHYSICAL-SEQUENTIAL ORDER 

DSN=addr 

Specifies that access of an indexed VTOC is by DSN order. 
BUFLIST is required if DSNONLY=NO is coded or defaulted. 

DSN omitted 

If you omit the DSN keyword, access of an indexed or 
nonindexed VTOC is by physical-sequential order. BUFLIST 
i s requi red. 



UCBIDEB: SPECIFY THE VTOC TO BE ACCESSED 



UCB= addr 

Supplies the address of the UCB for the unit whose VTOC is 
to be accessed. An unauthorized caller may not supply a 
UCB to CVAF. 

DEB=addr 

Supplies the address of a DEB opened to the VTOC to be 
accessed. CVAF will not allow output requests to the VTOC 
or VTOC index if DEB is supplied. No asynchronous requests 
may be performed by an unauthorized caller against the DEB 
(such as EXCP, CLOSE, EOV) because CVAF will remove the DEB 
from the DEB table for the duration of the CVAF call. An 
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unauthorized caller (neither APF authorized nor in a system 
key) must supply a DEB and not a UCB to CVAF. The 
unauthorized caller's DEB must have been created under the 
current task by either SAM or EXCP. 

If a previously obtained CVAF I/O area is supplied through the 
lOAREA keywords neither UCB nor DEB need be supplied. 

OtherNise^ either a UCB or DEB must be supplied. If a UCB 
address is supplied^ it Mill be overlaid in the CVPL Mith the 
UCB address in the I/O area. 

If DEB and UCB are supplied in the CVPL» the DEB Mill be used* 
and the UCB address supplied Mill be overlaid in the CVPL Mith 
the UCB address obtained from the DEB. 

DSNONLY: specify THAT ONLY THE DATA SET NAME BE READ 

This keyMord is applicable only to accessing an indexed VTOC in 
DSN order. 

DSNONLY=NO 

Requests that the data set name be obtained from the VTOC 
index and the DSCB be read into a buffer supplied through 
the BUFLIST keyMord. BUFLIST is required. 

DSNONLY=YES 

Requests that only the data set name be obtained from the 
VTOC index. If the ARC keyMord is coded* the argument of 
the DSCB is returned. 

ARG: SPECIFY UHERE THE ARGUMENT OF THE DSCB IS TO BE RETURNED 

This keyMord is applicable only to accessing an indexed VTOC in /f 
DSN order Mith DSNONLY=YES coded. 



\^^ 



ARG=addr 

Provides the address of the 5-byte area at Mhich the CCHHR 
of each data set name in the VTOC index is returned Mhen 
DSNONLY=YES is coded. 



IOAREA: keep OR FREE THE I/O UORK AREA 



IOAREA=KEEP 

Specifies the CVAF I/O area associated Mith the CVAF 
parameter list is to be kept upon completion of the CVAF 
request. IOAREA=KEEP may be coded Mith BRANCH=NO only if 
the caller is authorized (APF» or system key). 

If IOAREA=KEEP is coded* the caller must issue CVAF Mith 
IOAREA=NOKEEP specified at some future time* Mhether or not 
any further VTOC access is required^ for example* the 
recovery routine of the caller of CVAF. 

Coding IOAREA=KEEP alloNS subsequent CVAF requests to be 
more efficient* as certain initialization functions can be 
bypassed. Neither DEB nor UCB need be specified Mhen a 
previously obtained CVAF I/O area is supplied* neither can 
they be changed. 

When IOAREA=KEEP is first issued* CVAF returns the CVAF I/O 
area in the CVAF parameter list (CVIOAR). Subsequent calls 
of CVAF may use that same parameter list* and CVAF Mill 
obtain its I/O area from the CVIOAR. 

When processing on the current volume is finished* release 
all areas that Mere kept. 
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ZOAREA=CKEEP>fi£!d£) 

Provides the address of a previously obtained I/O area. If 
a different CVAF parameter list is used> the previously 
obtained CVAF I/O araa may be passed to CVAF by coding its 
address as the second parameter of the lOAREA keyMord. 



/^, 
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IOAREA=NOKEEP 

Causes the Mork area to be freed upon completion of the 
CVAF request. 

ZOAREA=(NOKEEP,addr) 

Causes a previously obtained Mork area to be freed upon 
completion of the CVAF request. 

XXRCDS: RETAIN VIERS IN VIRTUAL STORAGE 

This keyMord applies to an indexed VTOC only. 

IXRCDS=KEEP 

Specifies that the VIERs read into storage during the CVAF 
function are to be kept in virtual storage. The VIERs are 
retained even if the index function is unsuccessful. The 
VIERs are accessed from the CVAF parameter list (CVIRCDS). 
CVIRCDS is the address of a buffer list containing the VIR 
buffer addresses and RBAs of the VIERs read. 

Index search function Mill dynamically update the buffer 
list and» Mhen necessary^ obtain additional buffer lists 
and chain them together. 

If KEEP is specified and no buffer list is supplied to CVAF 
in the CVPL» CVAF will obtain a buffer list and buffers and 
read the first high-level VIER. The address of the buffer 
list is placed in the CVIRCDS field of the CVPL. The first 
high-level VIER will be checked for the VXFHLV bit and to 
see if the VXVISE bit is off. 

The buffer list and VIR buffers are in the caller's protect 
key. The subpool is if the caller is not authorized; 
subpool 229» if the caller is authorized. 

If IXRCDS=KEEP for an nonindexed VTOC» a request to read a 
DSCB may be performed* but an error code will be returned. 

Uhen processing on the current volume is finished* release 
all areas that were kept. 

IXRCDS=(KEEP,addr) 

The CVIRCDS from one CVAF call can be passed to another 
CVAF parameter list by specifying the address as the second 
parameter in the IXRCDS keyword. 

IXRCDS=NOKEEP 

If NOKEEP is coded* the VIERs which are accessed (if any) 
are not retained. Furthermore, the buffer list supplied in 
the CVIRCDS field in the CVAF parameter list is released* 
as are all buffers found in the buffer list. If the skip 
bit is set in any entry in the buffer list* the buffer and 
buffer list will not be freed. 

IXRCDS=(NOKEEP>addr) 

Specifies that previously accessed VIERs are not to be 
retained. 

You must free buffer lists and buffers obtained by CVAF. This 
can be done in three ways: 

• By coding IXRCDS=NOKEEP on the CVAFSEQ macro that obtained 
the buffers 

• By coding IXRCDS=NOKEEP on a subsequent CVAF macro 

• By coding CVAFDIR ACCESS=RLSE and providing the address of 
the buffer list in the BUFLIST keyword 

Note: To maintain the integrity of the VIERs read* you must 
enqueue the VTOC and reserve the unit. 
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branch: specify THE ENTRY TO THE NACRO 



BRANCH=(YES»SUP) 

Requests that the branch entry to CVAFDIR be used. The 
caller must be in supervisor state. Protect key checking 
i s bypassed. 

An 18-word save area must be supplied if BRANCH=YES is 
coded. No lock may be held on entry to CVAF. SRB mode is 
not alloixied. 

BRANCH~YES 

Equivalent to BRANCH=(YES,SUP), because SUP is the default 
uihen YES is coded. Protect key checking is bypassed. 

BRANCH=CYES>PGN) 

Requests the branch entry. The caller must be APF 
authorized and in problem state. Protect key checking is 
bypassed. 

BRANCH=NO 

Requests the SVC entry. The caller must be APF authorized 
if any output operations are requested. Protect key 
checking is performed. 



NF: specify THE FORM OF THE NACRO 



This keyword specifies whether the list or execute or normal 
form of the macro is requested. 



MF=I 



If I is coded» or neither L nor E is coded* the CVAF 
parameter list is generated as is code to call CVAF. This 
is the normal form of the macro. 



MF=L 



[ 
L indicates the list form of the macro. A parameter list \...-j^ 
is generated* but code to call CVAF is not generated. 

MF=(E,addr) 

E indicates the execute form of the macro. The remote CVAF 
parameter list supplied as 'addr* is used in and can be 
modified by the execute form of the macro. 



CVAFTST NACRO 



SYNTAX 



[label] 


CVAFTST 


UCB=addr 



UCB: SPECIFY THE VTOC TO BE TESTED 



UCB= addr 

Supplies the address of the UCB for the volume whose VTOC 
is to be tested. 
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APPENDIX B, EXAHPLES OF VTOC ACCESS MACROS 



The examples that folloui are partial assembly listings which 
include expansions of each VTOC access m^cro. The expansions 
are provided to shoM hoM the VTOC macros can be substituted for 
existing procedures. 

EXAMPLE l: USING THE CVAFDIR MACRO I4ITH AN INDEXED OR NONINDEXED VTOC 

This example uses the CVAFDIR macro to read a DSCB of a given 
data set name and determines Mhether the DSCB is for a 
partitioned data set. The address of the 44-byte data set name 
is supplied to the program i n register 5 (labeled RDSN in the 
example). The address of a DEB open to the VTOC is supplied to 
the program in register 4 (labeled RDEB in the example). 

The buffer list is in the program and is generated by the 
ICVAFBFL macro. The DSCB buffer is in the program and is 
generated by the lECSDSLl macro. 

EXAMPLEl CSECT 

STM 14,12,12(RSAVE) 

BALR 12,0 

USING x,12 

ST RSAVE,SAVEAREA+4 

LA RWORK,SAVEAREA 

ST RW0RK,8(,RSAVE) 

LR RSAVE,RUORK 

X REGISTERS 

REGISTER 1 

WORK REGISTER 

DEB ADDRESS 

ADDRESS OF DATA SET NAME 

SAVE AREA ADDRESS 

RETURN CODE REGISTER 15 

X RETURN CODES 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
PDSRTN EQU DATA SET A PDS RETURN CODE 

NOTFND EQU 4 DATA SET NOT FOUND RETURN CODE 

NOTPDS EQU 8 DATA SET NOT A PDS RETURN CODE 

UNEXPECD EQU 12 UNEXPECTED ERROR RETURN CODE 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X READ DSCB INTO DSIFMTID. 

X DATASET NAME ADDRESS SUPPLIED IN RDSN. 

X ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 

X DETERMINE IF DATA SET IS A PARTITIONED DATA SET. 

X THIS PROGRAM IS NEITHER REENTRANT NOR REUSABLE. 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
XC BUFLIST(BFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST 
01 BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
MVI BFLHNOE,! ONE BUFFER LIST ENTRY 

LA RWORK, DSIFMTID ADDRESS OF DSCB BUFFER 
ST RWORK,BFLEBUF PLACE IN BUFFER LIST 
01 BFLEFL,BFLECHR CCHHR OF DSCB RETURNED BY CVAF 
MVI BFLELTH,DSCBLTH DATA PORTION OF DSCB READ - DSN X 

SUPPLIED IN CVPL 
MVC DS1DSNAM,0(RDSN) MOVE IN DATA SET NAME TO WORKAREA 
CVAFDIR ACCESS=READ,DSN=DS1DSNAM,BUFLIST=BUFLIST,DEB=(RDEB) 



REGl 


EQU 


1 


RWORK 


EQU 


3 


RDEB 


EQU 


4 


RDSN 


EQU 


5 


RSAVE 


EQU 


13 


REGIS 


EQU 


15 
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+ 


CNOP 


0,4 


+ 


BAL 


1,ICV1E 


+ICV1S 


EQU 


X 


+ 


DC 


CL4*CVPL» 


+ 


DC 


AL2(ICV1E-ICV1S) 


+ 


DC 


XL1»01' 


+ 


DC 


XL1»00' 


+ 


DC 


B'OOOOOOOO' 


+ 


DC 


B'OOOOOOOO' 


+ 


DC 


H»0» 


+ 


DC 


A(0) 


+ 


DC 


A(DSIDSNAM) 


+ 


DC 


A(BUFLIST) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


ACO) 


+ 


DC 


A(0) 


+ 


DC 


ACO) 


+ 


DC 


ACO) 


+ 


DC 


ACO) 


+ 


DC 


ACO) 


+ 


DC 


ACO) 


+ICV1E 


EQU 


X 


+ 


ST 


RDEB»36C>1) 


+ 


SVC 


139 




USING CVPL,REG1 




LTR 


REGIS, REGIS 




BZ 


NOERROR 


X 
X 
if 


iXXXXXXXXXXXXXXXXXXXXXXXXXXX 


DETERMINE UHAT ERROR IS 


7% 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 




C 


REGIS, ERR0R4 




BNE 


OTHERERR 




CLI 


CVSTAT,STAT001 




BNE 


OTHERERR 




DROP 


REGl 


XXXXXXXM 

X 

X 

X 

xxxxxxxx 


IXXXXXXXXXXXXXXXXXXXXXXXXXXX 


DATA 


SET NAME NOT FOUND 


iXXXXXXXXXXXXXXXXXXXXXXXXXXX 




L 


RSAVE,4C,RSAVE) 




RETURN (14,12),RC=N0TFND 


+ 


LM 


14,12,12C13) 


+ 


LA 


1S,NOTFNDCO,0) 


+ 


BR 


14 


NOERROR 


EQU 


X 




MVC 


F1CCHHR,BFLECHR 1 



NOTFl 



CLI DS1FMTID,C»4» 

BE NOTFl 

TN DS1DS0RG,DS1DSGP0 

BO PDS 

EQU X 

L RSAVE,4C,RSAVE) 

RETURN C14,12),RC=N0TPDS 



LOAD CVPL LIST ADDRESS 

START OF CVPL 

EBCDIC »CVPL» 

LENGTH OF CVPL 

FUNCTION CODE 

STATUS INFORMATION 

FIRST FLAG BYTE 

SECOND FLAG BYTE 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR»S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 

STORE DEB PTR IN PARM LIST 

ADDRESSABILITY TO CVPL 
ANY ERROR 
BRANCH IF NOT 
xxxxxxxxxxxxxxxxxxxxxxxxxxxx 



xxxxxxxxxxxxxxxxxxxxxxxxx 

IS RETURN CODE 4 

BRANCH IF NOT 4 

IS IT DATA SET NAME NOT FOUND? 

BRANCH IF NOT 

ADDRESSABILITY TO CVPL NOT NEEDED 

xxxxxxxxxxxxxxxxxxxxxxxxx 



xxxxxxxxxxxxxxxxxxxxxxxxx 

SET UP DATA SET NOT FOUND ERROR 

RESTORE THE REGISTERS 
LOAD RETURN CODE 
RETURN 

DSCB READ 

MOVE CCHHR OF FORMAT 1/4 DSCB TO 

UORKAREA 

IS DSCB A FORMAT 4 DSCB 

BRANCH IF YES. NOT A FORMAT 1 

IS FORMAT 1 DSCB FOR PARTITIONED 

DATA SET 

BRANCH IF PDS 

DSCB IS NOT A PDS 

SET UP NOT PDS RETURN CODE 



.^ 






+ 


LM 14,12,12C13) 


RESTORE THE 


REGISTERS 


+ 


LA 15,NOTPDSC0,0) 


LOAD RETURN 


CODE 


+ 


BR 14 


RETURN 




PDS 


EQU X 

L RSAVE,4C,RSAVE) 


DATA SET IS PARTITIONED 






RETURN C14,12),RC=PDSRTN 


SET UP PDS RETURN CODE 




+ 


LM 14,12,12C13) 


RESTORE THE 


REGISTERS 


+ 


LA 15,PDSRTNC0,0) 


LOAD RETURN 


CODE 


+ 


BR 14 


RETURN 




OTHERERR 


EQU X 

L RSAVE,4C,RSAVE) 


UNEXPECTED ERROR 
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rf*****! 



RETURN (14,12),RC=UNEXPECD 
+ LM l<fr, 12, 12(13) RESTORE THE REGISTERS 

+ LA 15,UNEXPECD(0,0) LOAD RETURN CODE 

+ BR 14 RETURN 

ERR0R4 DC F'4» ERROR RETURN CODE 4 

BUFLIST ICVAFBFL DSECT=NO BUFFER LIST 
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,^'^\ 
^\^ 



o 



+BUFLIST 


DS 


OF 


+BFLHNOE 


DS 


XLl 


+BFLHFL 


DS 


XLl 


+ 


ORG 


BFLHFL 


+BFLHKEY 


DS 


XLl 


+BFLHVIR 


EQU 


X'08' 


+BFLHDSCB 


EQU 


X»04' 


+ 


DS 


XLl 


+BFLHSP 


DS 


XLl 


+BFLHFCHN 


DS 


A 


•i-x 






+BFLHLN 


EQU 


x-BUFLIST 



+X BUFFER LIST HEADER 

BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 

PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF, LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF. 

LIST 

LENGTH OF BUFFER LIST HEADER 

+X BUFFER LIST ENTRY 

BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

•TTR' OF ARGUMENT 

•RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 

FORMAT 1 DSCB DATASET NAME AND ) 

BUFFER 

FORMAT 1 DSCB 

DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 

DATA SET ORGANIZATION 
BYTE OF DSIDSORG 

IS - INDEXED SEQUENTIAL aOlA 

ORGANIZATION 

PS - PHYSICAL SEQUENTIAL SOIA 

ORGANIZATION 

DA - DIRECT ORGANIZATION aOlA 

CX - BTAM OR QTAM LINE GROUP aOlA 

RESERVED SOIA 

RESERVED aOlA 

PO - PARTITIONED ORGANIZATION aOlA 

U - UNMOVABLE, THE DATA aOlA 

CONTAINS LOCATION DEPENDENT 

INFORMATION 



+BFLE 


DS 


OF 


+BFLEFL 


DS 


XLl 


+BFLERBA 


EQU 


X'80^ 


+BFLECHR 


EQU 


X^40^ 


+BFLETTR 


EQU 


X^20^ 


+BFLEAUPD 


EQU 


X^IO' 


+BFLEMOD 


EQU 


X^08^ 


+BFLESKIP 


EQU 


X^04^ 


+BFLEIOER 


EQU 


X'02» 


+ 


DS 


XLl 


+BFLELTH 


DS 


XLl 


-i-x 






+BFLEARG 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XL3 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


X-BFLE 




lECSDSLl (1) 


+IECSDSL1 


EQU 


X 


+IECSDSF1 


EQU 


lECSDSLl 


+DS1DSNAM 


DS 


CL44 


+DS1FMTID 


DS 


CLl 


+DS1DSSN 


DS 


CL6 


+DS1V0LSQ 


DS 


XL2 


+DS1CREDT 


DS 


XL3 


+DS1EXPDT 


DS 


XL 3 


+DS1N0EPV 


DS 


XLl 


+DS1N0BDB 


DS 


XLl 


+x 






+ 


DS 


XLl 


+DS1SYSCD 


DS 


CL13 


+ 


DS 


XL7 


•^DSIDSORG 


DS 


XL2 


*ii 




FIR 


+DS1DSGIS 


EQU 


X^80' 


+x 






+DS1DSGPS 


EQU 


X'40^ 


+x 






+DS1DSGDA 


EQU 


X'20^ 


+DS1DSGCX 


EQU 


X^IO^ 


+x 


EQU 


X^08^ 


+x 


EQU 


X^04^ 


+DS1DSGP0 


EQU 


X^02^ 


+DS1DSGU 


EQU 


X'Ol' 


+X 






■l-X 






+ K 
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•I-DSIDSGGS 


EQU 


SECOND B 
X»80» 


+DS1DSGTX 


EQU 


X»40» 


+DS1DSGTQ 


EQU 


X'aO" 


+ X 


EQU 


X»10* 


+DS1ACBM 


EQU 


X'OS" 


+DS1DSGTR 


EQU 


X»04» 


•fx 


EQU 


X»02» 


+x 


EQU 


X'Ol' 


+DS1RECFM 


DS 


XLl 


+DS10PTCD 


DS 


XH 


+DS1BLKL 


DS 


XL2 


+DS1LRECL 


DS 


XL2 


+DS1KEYL 


DS 


XLl 


+DS1RKP 


DS 


XL2 


+DS1DSIND 


DS 


XLl 


+DS1SCAL0 


DS 


XL4 


+DS1LSTAR 


DS 


XL3 


+DS1TRBAL 


DS 


XL2 


+ 


DS 


XL2 


+DS1EXT1 


DS 


XLIO 


+x 


FIRST 


BYTE 


+x 


SECOND BYTE 


+x 


THIRE 


i - SIXTH BYTES 


+x 


SEVENTH - TENTH BYTES 


+DS1EXT2 


DS 


XLIO 


+DS1EXT3 


DS 


XLIO 


+DS1PTRDS 


DS 


XLS 


+DS1END 


EQU 


X 


DSCBLTH 


EQU 


x-IECSDSLl-L»DSl 


FICCHHR 


DS 


XLS 


SAVEAREA 


DS 


18F 


CVPL 


ICVAFPL , 



BLOCK 



aoiA 
aoiA 
aoiA 
aoiA 

dOlA 

aoiA 
aoiA 
aoiA 



GS - GRAPHICS ORGANIZATION 

TX - TCAM LINE GROUP 

TQ - TCAM MESSAGE QUEUE 

RESERVED 

ACCESS METHOD CONTROL 

TR - TCAM 370S 

RESERVED 

RESERVED 

RECORD FORMAT 

OPTION CODE 

BLOCK LENGTH 

RECORD LENGTH 

KEY LENGTH 

RELATIVE KEY POSITION 

DATA SET INDICATORS 

SECONDARY ALLOCATION 

LAST USED TRACK AND BLOCK ON TRACK 

BYTES REMAINING ON LAST TRACK USED 

RESERVED 

FIRST EXTENT DESCRIPTION 

EXTENT TYPE INDICATOR 

EXiEHT SEQUENCE NUMBER 

LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 

THIRD EXTENT DESCRIPTION 

POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 



CCHHR OF DSCB 

SAVE AREA 

CVPL MAPPING MACRO 



+x CVAF PARAMETER LIST 

+ XXXXXXXXXXXXXXX)(XXXXXXXXXXXXXX)(XX)()(KKKXX)()(XXX)(XKXMXKXMXXXXXKXXXXXXXXXXX 






+CVPL 


DSECT 




+ 


DS 


OF 


+CVLBL 


DS 


CL4 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XLl 


+CVDIRD 


EQU 


X»01» 


+CVDIWR 


EQU 


X'02» 


+CVDIRLS 


EQU 


X'03' 


+CVSEQGT 


EQU 


X'04» 


+CVSEQGTE 


EQU 


X»OS» 


+CVDMIXA 


EQU 


X»06' 


+CVDMIXD 


EQU 


X»07» 


+CVDMALC 


EQU 


X»08* 


+CVDMRLS 


EQU 


X»09» 


+CVDMMAP 


EQU 


X»OA» 


+CVVOL 


EQU 


X'OB» 


+CVVRFRD 


EQU 


X'OC» 


+CVVRFWR 


EQU 


X'OD* 


+CVSTAT 

+ 

+CVFL1 


DS 


XLl 


DS 


XLl 


+CV1IVT 


EQU 


X»80' 


+CV1I0AR 


EQU 


X»40' 


+CV1PGM 


EQU 


X»20» 


+CV1MRCDS 


EQU 


X'lO' 


+CV1IRCDS 


EQU 


X'08» 


+CV1MAPIX 


EQU 


X»04» 


+CV1MAPVT 


EQU 


X»02' 


+CV1MAPVL 


EQU 


X'Ol' 


+CVFL2 


DS 


XLl 


+CV2HIVIE 


EQU 


X»80' 


+CV2VRF 


EQU 


X'40» 


+CV2CNT 


EQU 


X»20» 


+CV2RCVR 


EQU 


X'10» 



CVAF PARAMETER LIST 

EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOM) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP = INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 
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+CV2SRCH 


EQU 


X'08» 


+CV2DSNLY 


EQU 


X»04' 


+CV2VER 


EQU 


X»02' 


+CV2NLEVL 


EQU 


X'01» 


+x 






+ 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CVVRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


J<-CVPL 



SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



+x VALUES OF CVSTAT 

+X(THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END 



EXAMPLE 2s USING THE CVAFDIR MACRO HUH AN INDEXED VTOC 



^X 



This example uses the CVAFDIR macro to read one or more DSCBs on 
a VTOC. The UCB is supplied to the program in register 4 
(labeled RUCB). The TTR of each DSCB read is to be returned to 
the caller. This program must be APF authorized. 

The address of a parameter list is supplied to the program in 
register 5 (labeled RLIST). The parameter list contains one or 
more 3-word entries. The format of each 3-word entry is mapped 
by the LISTMAP DSECT. The first word contains the address of 
the data set name of the DSCB to be read. The second word 
contains the address of the 96-byte buffer into which the DSCB 
is to be read. The third word contains the address of the 
3-byte TTR of the DSCB read. 

The CVPL is generated by a list form of the CVAFDIR macro at 
label CVPL. The BUFLIST. IXRCDS, lOAREA* and BRANCH keywords 
are coded on the list form of the macro. IXRCDS=KEEP and 
IOAREA=KEEP are coded to avoid overhead if two or more DSCBs are 
to be read. BRANCH=(YES»PGM) is coded in the list form of the 
CVAFDIR macro to cause the CVPL to have the CVIPGM bit set to 
one; this will indicate to CVAF that the caller is authorized by 
APF and not in supervisor state. The execute forms of the 
CVAFDIR macro then specify BRANCH=YES, and not BRANCH=(YES,PGM), 
because the CVIPGM bit is set in the list form of the macro. 

The CVAFDIR macro with ACCESS=RLSE is coded before the program 
exits in order to release the CVAF I/O area and the index 
records buffer list. BUFLIST=0 is coded because no 
user-supplied buffer list is to be released; BUFLIST was coded 
on the list form of the CVAFDIR macro and» therefore, is in the 
CVBUFL field of the CVPL. This field must be set to zero for 
the release. 
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EXAMPLE2 CSECT 
STM 
BALR 



14^2,12(13) 
12,0 



USING x,12 
ST 13,SAVEAREA+4 
LA RUORK,SAVEAREA 
ST RW0RK,8(,13) 
LR 13>RU0RK 

X REGISTERS 






RUORK EQU 3 

RUCB EQU 4 

RLIST EQU 5 

RDSN EQU 6 

RTTR EQU 7 

REGIS EQU 15 

X 

X 

X 
X 

X MORD 1 

X UiORD 2 

X UORD 3 
X 

X 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
USING LISTMAP, RLIST 

TOPLOOP EQU X 

XC BUFLIST(BFLHLN+BFL 
01 BFLHFL,BFLHDSCB 
MVI BFLHNOErl 
LA RWORK,LISTDSCB 
ST RWORK,BFLEBUF 
01 BFLEFL,BFLETTR 
MVI BFLELTH,DSCBLTH 



NO ERROR 
RELOOP 



WORK REGISTER 

UCB ADDRESS SUPPLIED BY CALLER 
ADDRESS OF PARAMETER LIST 
ADDRESS OF DATA SET NAME 
ADDRESS OF TTR 
RETURN CODE REGISTER 15 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

READ DSCB OF DATA SET NAME SUPPLIED. RETURN TTR OF DSCB. 
UCB ADDRESS SUPPLIED IN RUCB. 
ADDRESS OF PARAMETER LIST IN RLIST. 

OF PARAMETER LIST = ADDRESS OF DATA SET NAME 
OF PARAMETER LIST = ADDRESS OF DSCB TO BE RETURNED 
OF PARAMETER LIST = ADDRESS OF TTR TO BE RETURNED 
WORDS 1-3 DUPLICATED WITH THE HIGH ORDER BIT OF 
WORD 3 SET TO ONE FOR LAST ENTRY. 

XXXXXXXXXXXXXXXXXXXXXXXXXMXX 
ADDRESSABILITY TO PARMLIST 
LOOP FOR EACH DSCB 
ELN),BUFLIST ZERO BUFFER LIST 

DSCBS TO BE READ WITH BUFFER LIST 
ONE BUFFER LIST ENTRY 
ADDRESS OF DSCB BUFFER 
PLACE IN BUFFER LIST 
TTR OF DSCB RETURNED BY CVAF 
DATA PORTION OF DSCB READ - DSN X 
SUPPLIED IN CVPL 
ADDRESS OF DATA SET NAME 
(RUCB) ,MF=(E, CVPL) ,BRANCH=YES 

LOAD PARAMETER REG 1 
STORE UCB PTR IN FARM LIST 
STORE DSN PTR IN FARM LIST 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVT CVAF TABLE 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 
ADDRESS OF TTR TO BE RETURNED 
MAP OF TTR 
ANY ERROR 
BRANCH IF NOT 

ZERO TTR INDICATING NO DSCB 
GET NEXT ENTRY 
DSCB READ 

RETURN TTR OF DSCB 
GET NEXT ENTRY 
IS IT LAST ENTRY IN LIST? 
GET NEXT ENTRY 
PROCESS NEXT LIST 

RELEASE CVAF OBTAINED AREAS X 

RELEASE lOAREA X 

RELEASE VIER BUFFER LIST X 

NO USER BUFFER LIST SUPPLIED TO RLSEX 
BRANCH ENTER CVAF X 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 
RESET CVAF FLAGS OFF 
GET BUFLIST ADDRESS AND 



/^■■■"'x 



■^JL ^' 



L RDSN,LISTDSN 

CVAFDIR DSN=(RDSN),UCB= 

LA 1,CVPL 

ST RUCB,12(,1) 

ST RDSN, 16(a) 

L 15,16 

L 15,328(,15) 

L 15,12(,15) 

L 15,0(,15) 

BALR 14,15 

L RTTR,LISTTTR 

USING TTRMAP,RTTR 

LTR REG15,REG15 

BZ NOERROR 

XC TTR, TTR 

B RELOOP 

EQU X 

MVC TTR,BFLEATTR 

EQU X 

TM LASTLIST,LASTBIT 

LA RLIST, NEXTLIST 

BZ TOPLOOP 

CVAFDIR ACCESS=RLSE, 

IOAREA=NOKEEP, 

IXRCDS=NOKEEP, 

BUFLIST=0, 

BRANCH=YES, 

MF=(E,CVPL) 
LA 1,CVPL 
MVI 6(1),X'03' 
NI 8(1),B»10110111' 
LA 15,0 



^'-> 
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+ 


ST 


15,20(,1) 


+ 


L 


15,16 


+ 


L 


15,328(,15) 


+ 


L 


15,12(,15) 


+ 


L 


15,0(,15) 


+ 


BALR 


14,15 




L 


13,SAVEAREA+4 




RETURN (1^,12) 


+ 


LM 


14,12,12(13) 


+ 


BR 


14 


BUFLIST 


ICVAFBFL DSECT=NO 



STORE BUFLIST PTR IN PARM LIST 

LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 

LOAD THE CVT CVAF TABLE 

LOAD THE CVAF ADDRESS 

BRANCH AND LINK TO CVAF 



RESTORE THE REGISTERS 
RETURN 



BUFFER LIST 



+x BUFFER LIST HEADER 



+BUFLIST 


DS 


OF 


+BFLHNOE 


DS 


XLl 


+BFLHFL 


DS 


XLl 


+ 


ORG 


BFLHFL 


+BFLHKEY 


DS 


XLl 


+BFLHVIR 


EQU 


X'08' 


+BFLHDSCB 


EQU 


X'04' 


+ 


DS 


XLl 


+BFLHSP 


DS 


XLl 


+BFLHFCHN 


DS 


A 


+ x 






+BFLHLN 


EQU 


x-BUFLIST 



BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 

PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF. LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF. 

LIST 

LENGTH OF BUFFER LIST HEADER 



+X BUFFER LIST ENTRY 






+BFLE 


DS 


OF 


+BFLEFL 


DS 


XLl 


+BFLERBA 


EQU 


X»80' 


+BFLECHR 


EQU 


X'40» 


+BFLETTR 


EQU 


X''20' 


+BFLEAUPD 


EQU 


X'lO' 


+BFLEMOD 


EQU 


X'OS' 


+BFLESKIP 


EQU 


X»04' 


+BFLEIOER 


EQU 


X»02» 


+ 


DS 


XLl 


+BFLELTH 


DS 


XLl 


+x 






+BFLEARG 


DS 


XL5 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XL3 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


x-BFLE 


SAVEAREA 


DS 


18F 


LISTMAP 


DSECT 




LISTDSN 


DS 


F 


LISTDSCB 


DS 


F 


LISTTTR 


DS 


OF 


LASTLIST 


DS 


X 


LASTBIT 


EQU 


X'80' 




DS 


XL3 


NEXTLIST 


EQU 


X 


DSCB 


DSECT 






lECSDSLl (1) 


+IECSDSL1 


EQU 


x 


+IECSDSF1 


EQU 


lECSDSLl 


+DS1DSNAM 


DS 


CL44 


+DS1FMTID 


DS 


CLl 


+DS1DSSN 


DS 


CL6 



BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

'TTR' OF ARGUMENT 

'RBA' OF ARGUMENT 
BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
REGISTER SAVE AREA 

ADDRESS OF DATA SET NAME 

ADDRESS OF BUFFER FOR DSCB TO BE 

RETURNED 

ADDRESS OF TTR OF DSCB TO BE 

RETURNED 

FIRST BYTE 

LAST ENTRY IN LIST 

REMAINDER OF TTR ADDRESS 

NEXT LIST 



FORMAT 1 DSCB 

DATA SET NAME 
FORMAT IDENTIFIER 
DATA SET SERIAL NUMBER 
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+DS1V0LSQ 
+DS1CREDT 
+DS1EXPDT 
+DS1N0EPV 
+DS1N0BDB 

+ ■ 

+DS1SYSCD 
+ 

+DS1DS0RG 
+x 

+DS1DSGIS 
+DS1DSGPS 

+ K 

+DS1DSGDA 

+DS1DSGCX 

+ x 

+x 

+DS1DSGP0 

+DS1DSGU 

+x 

+x 

+x 

+x 

+DS1DSGGS 

+DS1DSGTX 

+DS1DSGTQ 

+x 

+DS1ACBM 

+DS1DSGTR 

+x 

+x 

+DS1RECFM 

+DS10PTCD 

+DS1BLKL 

+DS1LRECL 

+DS1KEYL 

+DS1RKP 

+DS1DSIND 

+DS1SCAL0 

+DS1LSTAR 

+DS1TRBAL 

+ 

+DS1EXT1 

+x 

+x 

+x 

+x 

+DS1EXT2 

+DS1EXT3 

+DS1PTRDS 

+DS1END 

DSCBLTH 

TTRMAP 

TTR 

EXAMPLE2 

CVPL 



+ 
+CVPL 

+ 
+ 
+ 
+ 
+ 
+ 



DS 
DS 
DS 
DS 
DS 

DS 
DS 
DS 
DS 

EQU 

EQU 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 



XL2 
XL3 
XL3 
XLl 
XLl 

XLl 
CL13 
XL7 
XL2 

X'80» 

X'40* 

X»20» 
X'lO' 
X»08» 
X'04» 
X'02» 
X*01» 



VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 

DATA SET ORGANIZATION 
FIRST BYTE OF DSIDSORG 

IS - INDEXED SEQUENTIAL 

ORGANIZATION 

PS - PHYSICAL SEQUENTIAL 

ORGANIZATION 

DA - DIRECT ORGANIZATION 

CX - BTAM OR QTAM LINE GROUP 

RESERVED 

RESERVED 

PO - PARTITIONED ORGANIZATION 

U - UNMOVABLE, THE DATA 

CONTAINS LOCATION DEPENDENT 

INFORMATION 



aoiA 

aoiA 

aoiA 
aoiA 
aoiA 
aoiA 
aoiA 
aoiA 



EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

FIRST 

SECOND BYTE 

THIRD - SIXTH BYTES 

SEVENTH - TENTH BYTES 



X»80' 

X'40» 

X'20» 

X»10' 

X»08» 

X»04» 

X'02' 

X»01' 

XLl 

XLl 

XL2 

XL2 

XLl 

XL2 

XLl 

XL4 

XL3 

XL2 

XL2 

XLIO 

BYTE 



aaiA 
aoiA 
aoiA 
aoiA 
aoiA 
aoiA 
aoiA 
aoiA 



SECOND BYTE OF DSIDSORG 

GS - GRAPHICS ORGANIZATION 

TX - TCAM LINE GROUP 

TQ - TCAM MESSAGE QUEUE 

RESERVED 

ACCESS METHOD CONTROL BLOCK 

TR - TCAM 3705 

RESERVED 

RESERVED 

RECORD FORMAT 

OPTION CODE 

BLOCK LENGTH 

RECORD LENGTH 

KEY LENGTH 

RELATIVE KEY POSITION 

DATA SET INDICATORS 

SECONDARY ALLOCATION 

LAST USED TRACK AND BLOCK ON TRACK 

BYTES REMAINING ON LAST TRACK USED 

RESERVED 

FIRST EXTENT DESCRIPTION 

EXTENT TYPE INDICATOR 

EXTENT SEQUENCE NUMBER 

LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 

THIRD EXTENT DESCRIPTION 

POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 



XLIO 
XLIO 
XLS 

X-DSCB-L'DSIDSNAM 



DS 

DS 

DS 

EQU 

EQU 

DSECT 

DS XL3 

CSECT 

CVAFDIR ACCESS=READ,BUFLIST=BUFLIST,MF=L, 

IOAREA=KEEP, 

IXRCDS=KEEP 



LENGTH OF DATA PORTION OF DSCB 
TTR TO BE RETURNED 



,^"^^. 



CHOP Or<t 

EQU X 

DC CL^'CVPL' 

DC AL2(ICV8E-CVPL) 

DC XL1»01' 

DC XL1»00» 

DC B»01001000» 

DC B'OOOOOOOO' 



KEEP lOAREA TO AVOID OVERHEAD X 
KEEP VIERS FOR 2ND AND SUBSEQUENT CALLSX 
CALLED IN PROGRAM STATE BUT APF X 
AUTHORIZED SO UCB IS SUPPLIED 



EBCDIC 'CVPL' 
LENGTH OF CVPL 
FUNCTION CODE 
STATUS INFORMATION 
FIRST FLAG BYTE 
SECOND FLAG BYTE 



\J 
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+ 


DC 


H'O' 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(BUFLIST) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ICV8E 


EQU 


n 




ORG 


CVPL 



RESERVED 
UCB ADDRESS 
DATA SET NAME ADDRESS 
BUFFER LIST ADDRESS 
INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I/O AREA ADDRESS 
DEB ADDRESS 
ARGUMENT ADDRESS 
SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 
NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 
COUNT AREA ADDRESS 
END OF CVPL 
OVERLAY CVPL WITH EXPANSION OF MAP 



CVPLMAP ICVAFPL DSECT=NO 



+x CVAF PARAMETER LIST 



o 



+CVPLMAP 


DS 


OF 


+CVLBL 


DS 


CL<i 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XLl 


+CVDIRD 


EQU 


X'Ol' 


+CVDIWR 


EQU 


X'02' 


+CVDIRLS 


EQU 


X'03' 


+CVSEQGT 


EQU 


X»04' 


+CVSEQGTE 


EQU 


X'05» 


+CVDMIXA 


EQU 


X'06» 


+CVDMIXD 


EQU 


X'07' 


+CVDMALC 


EQU 


X'08» 


+CVDMRLS 


EQU 


X'09» 


+CVDMMAP 


EQU 


X'OA» 


+CVVOL 


EQU 


X'OB» 


+CVVRFRD 


EQU 


X'OC 


+CVVRFWR 


EQU 


X»OD» 


+CVSTAT 

+ 

+CVFL1 


DS 


XLl 


DS 


XLl 


+CV1IVT 


EQU 


X*80' 


+CV1I0AR 


EQU 


X»40» 


+CV1PGM 


EQU 


X'20' 


+CV1MRCDS 


EQU 


X'lO' 


+CV1IRCDS 


EQU 


X»08» 


+CV1MAPIX 


EQU 


X'04' 


+CV1MAPVT 


EQU 


X»02' 


+CV1MAPVL 


EQU 


X'Ol' 


+CVFL2 


DS 


XLl 


+CV2HIVIE 


EQU 


X»80» 


+CV2VRF 


EQU 


X'^0» 


+CV2CNT 


EQU 


X»20' 


+CV2RCVR 


EQU 


X»10» 


+CV2SRCH 


EQU 


X'08' 


+CV2DSNLY 


EQU 


X'04» 


+CV2VER 


EQU 


X»02» 


+CV2NLEVL 


EQU 


X'Ol' 


-fX 






+ 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 



CVAF PARAMETER LIST 

EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOW) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR»S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
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+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CVVRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


x-CVPLMAP 



EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



+x VALUES OF CVSTAT 

+x(THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END 



EXAMPLE 3; USING THE CVAFSEQ MACRO WITH AN INDEXED VTOC 



This example uses the CVAFSEQ to count the number of ISAM data 
sets Mhose data set names are mi thin the range defined by two 
supplied data set names. The addresses of the tuio data set 
names are supplied to the program in registers 6 and 7» labeled 
RDSNl and RDSN2> respectively. The address of a DEB open to the 
VTOC is supplied in register 4» labeled RDEB. 

The CVAF parameter list is expanded by a list form of the 
CVAFSEQ macro. ACCESS=GTEQ is specified on the list form of the 
macro and is» therefore* not coded in the first execution of the 
CVPL. Subsequent executions of the CVPL (at label RELOOP) 
specify ACCESS=GT. 

End of data is tested by comparing the CVSTAT field to the value 
STAT032» Mhich is an equate in the ICVAFPL mapping macro. 

The count of ISAM DSCBs matching the data set name criterion is 
returned in register 15 unless an error is encountered* in Mhich 
case a negative one is returned in register 15. 



14,12,12(13) 
12,0 



EXAMPLES CSECT 
STM 
BALR 
USING X,12 
ST 13,SAVEAREA+4 
LA RWORK,SAVEAREA 
ST RW0RK,8(,13) 
LR 13,RW0RK 

a 

X REGISTERS 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

REGISTER 1 
WORK REGISTER 
DEB ADDRESS 

ADDRESS OF DATA SET NAME 1 
ADDRESS OF DATA SET NAME 2 
RETURN CODE REGISTER 15 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X COUNT THE NUMBER OF ISAM DATA SETS WHOSE DATA SET NAMES ARE 

X BETWEEN DSNl AND DSN2 INCLUSIVELY. 

X RDSNl CONTAINS ADDRESS OF DSNl. 

X RDSN2 CONTAINS ADDRESS OF DSN2. 

X ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
XC BUFLIST(BFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST 
01 BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
MVI BFLHN0E,1 ONE BUFFER LIST ENTRY 

LA RW0RK,DS1FMTID ADDRESS OF DSCB BUFFER 
ST RWORK,BFLEBUF PLACE IN BUFFER LIST 



(i ) 



REGl 


EQU 


1 


RWORK 


EQU 


3 


RDEB 


EQU 


4 


RDSNl 


EQU 


6 


RDSN2 


EQU 


7 


REGIS 


EQU 


15 



MVI BFLELTH,DSCBLTH 



DATA PORTION OF DSCB READ - DSN 
SUPPLIED IN CVPL 
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o 



LOOP 



MVC DS1DSNAM,0(RDSN1) 

XR RUIORK.RMORK 
CVAFSEQ DEB=(RDEB), 

BUFLIST=BUFLIST, 
MF=(E,CVPL) 
LA 1,CVPL 
ST RDEB,36(,1) 
SVC 139 
EQU X 



USING CVPL,REG1 
LTR REG15, REGIS 
BZ TESTDSN 

X DETERMINE WHAT ERROR I 

C REGIS, ERR0R4 

BNE OTHERERR 

CLI CVSTAT,STAT032 

BNE OTHERERR 

DROP REGl 



X 

xxxxxxxx 


END 


OF DATA 


xxxxxxxxxxxxxxxxxxxxxxx 




B 


RELEASE 


TESTDSN 


EQU 


X 




CLI 


DS1FMTID,C'1' 




BNE 


CKLAST 




CLC 


DS1DSNAM,0(RDSN2) 




BNH 


TESTIS 




B 


RELEASE 


TESTIS 


EQU 


X 




TM 


DS1DS0RG,DS1DSGIS 




BZ 


CKLAST 




LA 


RUIORK.ICRUORK) 


CKLAST 


EQU 


X 




CLC 


DS1DSNAM,0(RDSN2) 




BNH 


RELOOP 




B 


RELEASE 


RELOOP 


EQU 


X 




CVAFSEQ ACCESS=GT,MF=( 


+ 


LA 


1,CVPL 


+ 


MVI 


6(1),X'0<J' 


+ 


SVC 


139 




B 


LOOP 


OTHERERR 


EQU 


X 


xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 


X 
X 

xxxxxxxx 


UNEXPECTED ERROR PROCE 


xxxxxxxxxxxxxxxxxxxxxxx 




LA 


RWORK, 1(6,0) 




LNR 


RWORK,RWORK 


RELEASE 


CVAFDIR ACCESS=RLSE, 






BUFLIST=0, 






IXRCDS=NOKEEP, 






MF=(E,CVPL) 


+RELEASE 


EQU 


X 


+ 


LA 


1,CVPL 


+ 


MVI 


6(1),X'03' 


+ 


NI 


8(1),B'11110111' 


+ 


LA 


1S,0 


+ 


ST 


1S,20(,1) 


+ 


SVC 


139 




LR 


REGIS, RWORK 




L 


13,SAVEAREA+4 



MOVE IN STARTING DATA SET NAME TO X 

WORKAREA 

ZERO COUNT 

FIND FIRST DATA SET WHOSE DATA SET X 

NAME IS GREATER THAN OR EQUAL TO x 

THAT OF DSNl 

LOAD PARAMETER REG 1 
STORE DEB PTR IN FARM LIST 

LOOP UNTIL END OF DATA OR DATA SET x 
NAME GREATER THAN DSN2 
ADDRESSABILITY TO CVPL 
ANY ERROR 

BRANCH IF NOT-CHECK DSN LIMIT 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

IS RETURN CODE ^ 

BRANCH IF NOT 4 

IS IT END OF DATA? 

BkAHCH IF NOT 

ADDRESSABILITY TO CVPL NOT NEEDED 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

RELEASE CVAF RESOURCES AND RETURN 

IS DATA SET NAME GREATER THAN DSN2 

IS THIS A FORMAT 1 DSCB? 

BRANCH IF NO. CAN NOT BE ISAM. 

HAS LIMIT BEEN REACHED? 

BRANCH IF NO-TEST FOR ISAM 

RELEASE CVAF RESOURCES AND RETURN 

ONLY COUNT ISAM 

IS DATA SET ISAM 

BRANCH IF NO-DO NOT COUNT IT 

INCREMENT COUNT BY ONE 

CHECK IF LAST DATA SET NAME (DSN2) 

HAS LIMIT BEEN REACHED? 

BRANCH IF NO-READ NEXT ONE 

RELEASE CVAF RESOURCES AND RETURN 

READ NEXT DSCB 
E,CVPL) GET DSCB WITH DATA SET NAME 

GREATER THAN THE ONE LAST READ 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 

CHECK RESULTS OF CVAFSEQ 
UNEXPECTED ERROR 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
ONE IN RWORK 

SET NEGATIVE COUNT INDICATING ERROR 
RELEASE CVAF BUFFERS/IOAREA X 

DO NOT RELEASE USER BUFFER LIST X 
RELEASE CVAF VIER BUFFERS X 

RELEASE CVAF I/O ARE^ 

LOAD PARAMETER REG 1 
SET FUNCTION CODE 
RESET CVAF FLAGS OFF 
GET BUFLIST ADDRESS AND 
STORE BUFLIST PTR IN FARM LIST 

CURRENT COUNT IS RETURN CODE 
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ERRORS 
BUFLIST 



RETURN (14,12),RC=(15) 
L 14,12(13,0) 
LM 0,12,20(13) 
BR 14 
DC F'4» 
ICVAFBFL DSECT=NO 



RETURN CURRENT COUNT 

RESTORE REGISTER 14 
RESTORE THE REGISTERS 
RETURN 

ERROR RETURN CODE 4 

BUFFER LIST 



+X BUFFER LIST HEADER 



+BUFLIST 


DS 


OF 


+BFLHNOE 


DS 


XLl 


+BFLHFL 


DS 


XLl 


+ 


ORG 


BFLHFL 


+BFLHKEY 


DS 


XLl 


+BFLHVIR 


EQU 


X»08» 


+BFLHDSCB 


EQU 


X*04» 


+ 


DS 


XLl 


+BFLHSP 


DS 


XLl 


+BFLHFCHN 


DS 


A 


+x 






+BFLHLN 


EQU 


x-BUFLIST 



BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 

PROTECT KEY (FIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF. LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF, LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF. 

LIST 

LENGTH OF BUFFER LIST HEADER 

+x BUFFER LIST ENTRY 

BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

»TTR» OF ARGUMENT 

'RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 

FORMAT 1 DSCB DATASET NAME AND i 

BUFFER 

FORMAT 1 DSCB 

DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 

DATA SET ORGANIZATION 
BYTE OF DSIDSORG 

IS - INDEXED SEQUENTIAL aOlA 

ORGANIZATION 

PS - PHYSICAL SEQUENTIAL aOlA 

ORGANIZATION 

DA - DIRECT ORGANIZATION aOlA 



+BFLE 


DS 


OF 


+BFLEFL 


DS 


XLl 


+BFLERBA 


EQU 


X'80' 


+BFLECHR 


EQU 


X'40' 


+BFLETTR 


EQU 


X'20' 


+BFLEAUPD 


EQU 


X'lO' 


+BFLEMOD 


EQU 


X'OS* 


+BFLESKIP 


EQU 


X'04» 


+BFLEIOER 


EQU 


X'02» 


+ 


DS 


XLl 


+BFLELTH 


DS 


XLl 


•i-X 






+BFLEARG 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XL3 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL4 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


x-BFLE 




lECSDSLl (1) 


+IECSDSL1 


EQU 


X 


+IECSDSF1 


EQU 


lECSDSLl 


+DS1DSNAM 


DS 


CL44 


+DS1FMTID 


DS 


CLl 


+DS1DSSN 


DS 


CL6 


+DS1V0LSQ 


DS 


XL2 


+DS1CREDT 


DS 


XL3 


+DS1EXPDT 


DS 


XL3 


+DS1N0EPV 


DS 


XLl 


+DS1N0BDB 


DS 


XLl 


+x 






+ 


DS 


XLl 


+DS1SYSCD 


DS 


CL13 


+ 


DS 


XL7 


+DS1DS0RG 


DS 


XL2 


+x 




FIR 


+DS1DSGIS 


EQU 


X'80' 


+x 






+DS1DSGPS 


EQU 


X'40' 


+x 






+DS1DSGDA 


EQU 


X'20' 
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-I-DSIDSGCX EQU X*10* CX - BTAN OR QTAM LINE OROUP 3G1A 

•^ +K EQU X»08» RESERVED aOlA 

l!^ -i-H EQU X*04* RESERVED dOlA 

kJ -I-DSIDSGPO EQU X'02» PO - PARTITIONED ORGANIZATION 301 A 
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\J 












•I^DSIDSGU 

*H 
+x 

+DS1DSGGS 
+DS1DSGTX 
+DS1DSGTQ 
+x 

+DS1ACBM 
+DS1DSGTR 
+x 
•fx 

+DS1RECFM 
+DS10PTCD 
+DS1BLKL 
+DS1LRECL 
+DS1KEYL 
+DS1RKP 
+DS1DSIND 
•i-DSlSCALO 
+DS1LSTAR 
+DS1TRBAL 
+ 

+DS1EXT1 
+x 
+x 
+x 
+x 

+DS1EXT2 
+DS1EXT3 
+DS1PTRDS 
+DS1END 
DSCBLTH 
SAVEAREA 
CVPL 



+ 

+CVPL 

+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ICV10E 



EQU 



X»01' 



U - UNMOVABLE, THE DATA 
CONTAINS LOCATION DEPENDENT 
INFORMATION 



aoiA 



X'80» 

X»40' 

X»20' 

X'lO* 

X»08' 

X»04» 

X»02» 

X»01» 

XLl 

XLl 

XL2 

XL2 

XLl 

XL2 

XLl 

XL<» 

XL3 

XL2 

XL2 



SECOND BYTE OF DSIDSORG 

6S - GRAPHICS ORGANIZATION aOlA 

TX - TCAM LINE GROUP aOlA 

TQ - TCAM MESSAGE QUEUE aOlA 

RESERVED aOlA 

ACCESS METHOD CONTROL BLOCK aOlA 

TR - TCAM 3705 aOlA 

RESERVED aOlA 

RESERVED aOlA 

RECORD FORMAT 

OPTION CODE 

BLOCK LENGTH 

RECORD LENGTH 

KEY LENGTH 

RELATIVE KEY POSITION 

DATA SET INDICATORS 

SECONDARY ALLOCATION 

LAST USED TRACK AND BLOCK ON TRACK 

BYTES REMAINING ON LAST TRACK USED 

RESERVED 

FIRST EXTENT DESCRIPTION 

EXTENT TYPE INDICATOR 

EXTENT SEQUENCE NUMBER 

LOUER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 

THIRD EXTENT DESCRIPTION 

POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 



EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS XLIO 

FIRST BYTE 

SECOND BYTE 

THIRD - SIXTH BYTES 

SEVENTH - TENTH BYTES 

DS XLIO 

DS XLIO 

DS XLS 

EQU X 

EQU X-IECSDSL1-L»DS1DSNAM LENGTH OF DATA PORTION OF DSCB 



DS 18F 

CVAFSEQ ACCESS=GTEQ, 
IXRCDS=KEEP, 
DSN=DS1DSNAM» 
BUFLIST=BUFLIST, 
MF=L 

CHOP 0»<» 

EQU X 

DC CL4»CVPL' 

DC AL2(ICV10E-CVPL) 

DC XLl'05' 

DC XL1»00' 

DC B'OOOOIOOO* 

DC B*00000000* 

DC H»0» 

DC A(0) 

DC A(DSIDSNAM) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

DC A(0) 

EQU X 

ORG CVPL 



CVPLMAP ICVAFPL DSECT=NO 



SAVE AREA 

READ DSCB UITH DSN >= SUPPLIED DSN X 

KEEP VIERS IN STORAGE DURING CALLS x 

SUPPLIED DATA SET NAME X 



EBCDIC 'CVPL' 

LENGTH OF CVPL 

FUNCTION CODE 

STATUS INFORMATION 

FIRST FLAG BYTE 

SECOND FLAG BYTE 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEU VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 
EXPAND MAP OVER LIST 
CVPL MAP 



•l-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
+x CVAF PARAMETER LIST 

-fXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
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+CVPLMAP 


DS 


OF 


+CVLBL 


DS 


CL4 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XLl 


+CVDIRD 


EQU 


X'Ol' 


+CVDIWR 


EQU 


X»02» 


+CVDIRLS 


EQU 


X»03» 


+CVSEQ6T 


EQU 


X'O^* 


+CVSEQGTE 


EQU 


X»05» 


+CVDMIXA 


EQU 


X'06» 


+CVDMIXD 


EQU 


X'07' 


+CVDMALC 


EQU 


X»08» 


+CVDMRLS 


EQU 


X'09* 


+CVDMMAP 


EQU 


X»OA' 


+CVVOL 


EQU 


X'OB* 


+CVVRFRD 


EQU 


X'OC 


+CVVRFWR 


EQU 


X'OD' 


+CVSTAT 

+ 

+CVFL1 


DS 


XLl 


DS 


XLl 


+CV1IVT 


EQU 


X»80» 


+CV1I0AR 


EQU 


X'AO' 


+CV1PGM 


EQU 


X»20* 


+CV1MRCDS 


EQU 


X»10» 


+CV1IRCDS 


EQU 


X»08» 


+CV1MAPIX 


EQU 


X»04» 


+CV1MAPVT 


EQU 


X»02» 


+CV1MAPVL 


EQU 


X'Ol* 


+CVFL2 


DS 


XLl 


+CV2HIVIE 


EQU 


X'80» 


+CV2VRF 


EQU 


X»40' 


+CV2CNT 


EQU 


X»20» 


+CV2RCVR 


EQU 


X'lO' 


+CV2SRCH 


EQU 


X»08' 


+CV2DSNLY 


EQU 


X'04' 


+CV2VER 


EQU 


X'02' 


+CV2NLEVL 


EQU 


X'Ol' 


4^K 






+ 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CVVRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


X-CVPLMAP 



CVAF PARAMETER LIST 

EBCDIC »CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS-READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFD.SM ACCESS = IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOUI) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR»S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 






+x VALUES OF CVSTAT 

+X(THIS PART OF THE ICVAFPL MACRO EXAPNSION IS NOT SHOWN) 
END 



EXAMPLE ^; USING THE CVAFSEQ MACRO WITH A NONINDEXED VTOC 



This example reads up to five DSCBs in physical-sequential 
order. The address of the UCB is supplied to the program in 
register 5 (labeled RUCB). The address of a parameter list is 
supplied in register 4 (labeled RLIST). The first word of the 
parameter list contains the address of a 5-byte field. On 
entry, this field i s set to zero if no previous DSCBs have been 
read; otherMise, the field is set to the CCHHR of the last DSCB 
read. This 5-byte field is supplied by the caller of this 
program and is not modified by this program. 
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The remainder of the parameter list consists of one or more 
2-word entries^ up to a maximum of five 2-word entries. The 
first word of each entry contains the address of a 140-byte DSCB 
buffer. The second word contains the address of a 5-byte field 
that is to contain the CCHHR of the DSCB. 

A buffer list with five buffer list entries is contained in the 
program. The ICVAFBFL macro generates the buffer list header and 
one buffer list entry. The remaining buffer list entries are 
generated following the ICVAFBFL macro. 

The CVAFSEQ macro is used once in the program to read as many 
DSCBs as there are 2-word entries in the parameter list. The 
buffer list header field BFLHNOE is initialized with the number 
of buffer list entries that CVAFSEQ is to process. The number 
matches the number of 2-word entries in the parameter list 
supplied to this program. 

After the CVAFSEQ call» the CCHHR for each DSCB read is moved 
from the buffer list entry field BFLEARG to the field whose 
address is supplied by the caller of the program. If the 
BFLEARG field is zero» the previous DSCB read was the last in 
the VTOC. 

The BFLEARG in the first buffer list entry is initialized with 
the CCHHR supplied by the caller^ its address i s the third word 
in the parameter list. This CCHHR serves as the starting place 
for the CVAFSEQ call. DSCBs with a CCHHR greater than the 
supplied CCHHR are read. 

This program must be APF authorized. 

EXAMPLE<i CSECT 

STM 14,12,12(13) 

BALR 12,0 

USING x,l2 

ST 13,SAVEAREA+4 

LA RU10RK,SAVEAREA 

ST RW0RK,8(,13) 

LR 13,RU0RK 

a 

X REGISTERS 

REGISTER 1 

WORK REGISTER 

ADDRESS OF FARM LIST 

UCB ADDRESS 

CURRENT ENTRY IN FARM LIST 

CURRENT BUFFER LIST ENTRY 

COUNT OF ENTRIES IN BUFFER LIST 

RETURN CODE REGISTER 15 

X READ UP TO 5 DSCBS. 

X RUCB CONTAINS ADDRESS OF UCB. 

X RLIST CONTAINS ADDRESS OF PARAMETER LIST, 

X WORD = ADDRESS OF CCHHR OF LAST DSCB READ. THIS DSCB IS 

X NOT TO BE READ 

X WORD 1 = ADDRESS OF DSCB BUFFER. 

X WORD 2 = ADDRESS OF CCHHR OF DSCB READ. 

X WORDl AND W0RD2 REPEATED UP TO 4 TIMES. 

X HIGH ORDER BIT OF WORD 2 SET TO ONE FOR LAST ENTRY. 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

USING LIST, RLIST ADDRESSABILITY TO FARM LIST 

XC BFLHDR(BFLHLN+5XBFLELN),BFLHDR ZERO BUFFER LIST J^ITH » 

5 BUFFER LIST ENTRIES 



REGl 


EQU 


1 


RWORK 


EQU 


3 


RLIST 


EQU 


4 


RUCB 


EQU 


5 


RCURRENT 


EQU 


6 


RBLE 


EQU 


7 


RCOUNT 


EQU 


8 


REGIS 


EQU 


15 
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01 BFLHFL,BFLHDSCB 

LA RCURRENT^LISTPRMS 

USING LISTPRMS,RCURRENT 

LA RBLE,BFLE 

USING BFLE.RBLE 

L RWORK,LISTSTRT 

NVC BFLEARG>0(RMORK} 



DSCBS TO BE READ WITH BUFFER LIST 
FIRST DOUBLEWORD ENTRY IN FARM LIST 
USING ON DOUBLEUiORDS 
FIRST BUFFER LIST ENTRY 



J 



BUFLOOP 



XR 
EQU 

LA 

L 

ST 

MVI 

TM 

LA 

LA 

BZ 

STC 



ADDRESS OF STARTING CCHHR 

MOVE STARTING CCHHR INTO FIRST X 

BUFFER LIST ENTRY 

ZERO COUNT 

PUT BUFFER ADDRESSES IN BUFFER LIST K 

ENTRIES 

INCREMENT COUNT 

ADDRESS OF DSCB BUFFER 
RWORK,BFLEBUF-BFLE(,RBLE) PLACE IN BUFFER LIST 
BFLELTH-BFLE(RBLE),DSCBLTH FULL DSCB READ 



RCOUNT,RCOUNT 

RC0UNT,1(,RC0UNT) 
RWORK,LISTBUF 



LISTLAST,LASTBIT 

RCURRENT,LISTNEXT 

RBLE,BFLELN(,RBLE) 

BUFLOOP 

RCOUNT,BFLHNOE 



IS IT LAST ENTRY IN LIST 
INCREMENT TO NEXT ENTRY IN LIST 
INCREMENT TO NEXT BUFFER LIST ENTRY 
LOOP TO PUT NEXT BUFFER IN BFLE 
SET NUMBER OF ENTRIES IN BUFFER 
LIST HEADER 
DROP RCURRENT,RBLE 

K)()(X)(X)(XXXXXXX)()(KKXXKXX)(KXX)(XKXXXK)(XX)CX)(X)(XXX)(KXX)(X)(XKX)(X}(XX 

X 

K READ UP TO 5 DSCBS WHOSE CCHHR IS GREATER THAN THE CCHHR IN 

X THE FIRST BUFFER LIST ENTRY 

X 

XXXXXXXXXXXXXXXKXXXXXXKXXXXXXXXXXXXXiCXXXJtXXXXXXXXXXXXXXXXXXX 

CVAFSEQ UCB=(RUCB), CALL CVAF 

BRANCH=YES, BRANCH ENTER 
MF=(E,CVPL) 
+ LA 1,CVPL LOAD PARAMETER REG 1 

STORE UCB PTR IN FARM LIST 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVAF TABLE ADDRESS 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 
ADDRESSABILITY TO CVPL 
ANY ERROR 
BRANCH IF MOVE IN CCHHRS 

XXKXXXXXXXKXXXXXX)()()(XX)()()(XXXXXXXXX)(XXXX)(X)()(K)(}(XKX}(XXXXXXXXXX 

X 

X DETERMINE WHAT ERROR IS 

X 
XX)(XXXXXX)(XXXXXX)(XXXX)(XXXX)(X)()(XXXXXXXXXM)(}()(X)(X)()(XXX)()(X}(XXXMX 

C REGIS, ERR0R4 IS RETURN CODE 4 

BNE OTHERERR BRANCH IF NOT 4 

CLI CVSTAT,STAT032 IS IT END OF DATA? 

BNE OTHERERR BRANCH IF NOT 

DROP REGl ADDRESSABILITY TO CVPL NOT NEEDED 

XXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)(K)(}(XX}(XXXXXX)(KXXXXX}()(XXX 
X 

X DETERMINE IF ANY DSCBS HAVE BEEN READ. BFLEARG IS NON-ZERO 
X IN EACH BUFFER LIST ENTRY FOR WHICH A DSCB HAS BEEN READ 
X 

XXXXX)(XXX)(XXXXXXMXXXXXXXXXXXX)(XXXX}(K)(XX)(XXXXXXXXX)(XXXXX)()(XXX 



+ 


ST 


RUCB,12(,1) 


+ 


L 


15,16 


+ 


L 


15,328(,15) 


+ 


L 


15,12(,15) 


+ 


L 


15,0(,15) 


+ 


BALR 


14,15 




USING CVPL, REGl 




LTR 


REG15,REG15 




BZ 


MOVECHR 



r ' \ 



MOVECHR EQU X 

LA RCURRENT,LISTPRMS 
USING LISTPRMS,RCURRENT 
LA RBLE,BFLE 
USING BFLE,RBLE 

CHRLOOP EQU x 

RWORK,LISTCHR 



IS DATA SET NAME GREATER THAN DSN2 
FIRST ENTRY IN FARM LIST 

FIRST BUFFER LIST ENTRY 



MOVE CCHHR ARGUMENT TO CALLER AREA 

L RWORK,LISTCHR ADDRESS OF CCHHR OF CALLER 

XC 0(L*BFLBARG,RWORK),0(RWORK) ZERO CALLER CCHHR AREA 

NC BFLEARG, BFLEARG IS CCHHR ZERO 

BZ EXIT BRANCH IF YES-NO MORE DSCBS 

MVC 0(L 'BFLEARG, RWORK), BFLEARG MOVE CCHHR TO CALLER AREA 

TM LISTLAST,LASTBIT LAST ENTRY IN FARM LIST? 

BO EXIT BRANCH IF YES 
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LA RCURRENT,LISTNEXT 




LA RBLE.BFLELNCRBLE) 




B CHRLOOP 


EXIT 


EQU X 




L 13,SAVEAREA+4 




RETURN (14,12) 


+ 


LM 14,12,12(13) 


+ 


BR 14 



NEXT ENTRY IN LIST 
NEXT BUFFER LIST ENTRY 
TEST NEXT BFLE 
RETURN TO CALLER 



RESTORE THE REGISTERS 
RETURN 
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// ~x 



%^ 



OTHERERR EQU X 

B EXIT 
ERR0R4 DC F'<t' 

ICVAFBFL DSECT=NO 



ERROR PROCESSING 



RETURN 

RETURN CODE <♦ 

BUFFER LIST WITH ONE BUFFER LIST 

ENTRY 



+X BUFFER LIST HEADER 



+BFLHDR 


DS 


OF 


+BFLHNOE 


DS 


XLl 


+BFLHFL 


DS 


XLl 


+ 


ORG 


BFLHFL 


+BFLHKEY 


DS 


XLl 


+BFLHVIR 


EQU 


X»08' 


+BFLHDSCB 


EQU 


X»04» 


+ 


DS 


XLl 


+BFLHSP 


DS 


XLl 


+BFLHFCHN 


DS 


A 


+ x 






+BFLHLN 


EQU 


X-BFLHDR 



BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 

PROTECT KEY (FIRST ^ BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 

BUF. LIST ENTRIES DESCRIBE DSCBS 

RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 

FORWARD CHAIN PTR TO NEXT BUF, 

LIST 

LENGTH OF BUFFER LIST HEADER 



+x BUFFER LIST ENTRY 
•fXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)(XXXXXXXXXXXXXXXXXXXXXXXXXXXXX 






+BFLE 


DS 


OF 


+BFLEFL 


DS 


XLl 


+BFLERBA 


EQU 


X'80* 


+BFLECHR 


EQU 


X'^O' 


+BFLETTR 


EQU 


X'20' 


+BFLEAUPD 


EQU 


X»10' 


+BFLEMOD 


EQU 


X'08' 


+BFLESKIP 


EQU 


X»0<t' 


+BFLEIOER 


EQU 


X'02» 


+ 


DS 


XLl 


+BFLELTH 


DS 


XLl 


+x 






+BFLEARG 


DS 


XLS 


+ 


ORG 


BFLEARG+1 


+BFLEATTR 


DS 


XL3 


+ 


ORG 


BFLEARG+1 


+BFLEARBA 


DS 


XL^ 


+BFLEBUF 


DS 


A 


+BFLELN 


EQU 


X-BFLE 




DS 


CL(<iXBFLELN) 


SAVEAREA 


DS 


18F 


DSCB 


DSECT 




lECSDSLl (1) 


+IECSDSL1 


EQU 


X 


+IECSDSF1 


EQU 


lECSDSLl 


+DS1DSNAM 


DS 


CL<»4 


+DS1FMTID 


DS 


CLl 


+DS1DSSN 


DS 


CL6 


+DS1V0LSQ 


DS 


XL2 


+DS1CREDT 


DS 


XL3 


+DS1EXPDT 


DS 


XL3 


+DS1N0EPV 


DS 


XLl 


-t-DSlNOBDB 


DS 


XLl 


+x 






+ 


DS 


XLl 


+DS1SYSCD 


DS 


CL13 


+ 


DS 


XL7 


+DS1DS0RG 


DS 


XL2 



BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 

ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 

DATA IN BUF. HAS BEEN MODIFIED 

SKIP THIS ENTRY 

I/O ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 

LENGTH OF VIR DIVIDED BY 256 

ARGUMENT OF VIR OR DSCB (CCHHR) 

»TTR' OF ARGUMENT 

'RBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
FOUR BUFFER LIST ENTRIES 
SAVE AREA 

FORMAT 1 DSCB DATASET NAME AND 

DATA 

FORMAT 1 DSCB 

DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 

DIRECTORY BLOCK 
RESERVED 
SYSTEM CODE 
RESERVED 
DATA SET ORGANIZATION 
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+x 




FIRST BYTE 


+DS1DSGIS 


EQU 


X»80» 


+ M 






+DS1DSGPS 


EQU 


X'40' 


+ x 






+DS1DSGDA 


EQU 


X»20' 


+DS1DSGCX 


EQU 


X»10» 


+x 


EQU 


X'08' 


+x 


EQU 


X»04' 


+DS1DSGP0 


EQU 


X»02' 


+DS1DSGU 


EQU 


X»01' 


+x 






+x 






+x 






+x 




SECOND BYT 


+DS1DSGGS 


EQU 


X»80» 


+DS1DSGTX 


EQU 


X'40' 


+DS1DSGTQ 


EQU 


X»20» 


+ X 


EQU 


X'10» 


+DS1ACBM 


EQU 


X»08' 


+DS1DSGTR 


EQU 


X'04' 


+}< 


EQU 


X'02' 


+x 


EQU 


X'01» 


+DS1RECFM 


DS 


XLl 


+DS10PTCD 


DS 


XLl 


+DS1BLKL 


DS 


XL2 


+DS1LRECL 


DS 


XL2 


+DS1KEYL 


DS 


XLl 


+DS1RKP 


DS 


XL2 


+DS1DSIND 


DS 


XLl 


+DS1SCAL0 


DS 


XL4 


+DS1LSTAR 


DS 


XL3 


+DS1TRBAL 


DS 


XL2 


+ 


DS 


XL2 


+DS1EXT1 


DS 


XLIO 


+J( 


FIRST 


BYTE 


+ x 


SECOND BYTE 


+ X 


THIRD 


- SIXTH BYTES 


+ )( 


SEVENTH - TENTH BYTES 


+DS1EXT2 


DS 


XLIO 


+DS1EXT3 


DS 


XLIO 


+DS1PTRDS 


DS 


XLS 


+DS1END 


EQU 


X 


DSCBLTH 


EQU 


K-IECSDSLl 


LIST 


DSECT 




LISTSTRT 


DS 


F 


LISTPRMS 


EQU 


X 


LISTBUF 


DS 


F 


LISTCHR 


DS 


OF 


LISTLAST 


DS 


X 


LASTBIT 


EQU 


X'80» 




DS 


AL3 


LISTNEXT 


EQU 


X 


EXAMPLES 


CSECT 






K 

ii 


READ 


DSCBS WITH CCHHR G! 




BUFFER LIST ENTRY. 



OF DSIDSORG 

IS - INDEXED SEQUENTIAL 

ORGANIZATION 

PS - PHYSICAL SEQUENTIAL 

ORGANIZATION 

DA - DIRECT ORGANIZATION 

CX - BTAM OR QTAM LINE GROUP 

RESERVED 

RESERVED 

PO - PARTITIONED ORGANIZATION 

U - UNMOVABLE, THE DATA 

CONTAINS LOCATION DEPENDENT 

INFORMATION 



aoiA 

aoiA 

aoiA 
aoiA 
aoiA 
aoiA 
aoiA 
aoiA 



E OF DSIDSORG 

GS - GRAPHICS ORGANIZATION aOlA 

TX - TCAM LINE GROUP aOlA 

TQ - TCAM MESSAGE QUEUE aOlA 

RESERVED aOlA 

ACCESS METHOD CONTROL BLOCK aOlA 

TR - TCAM 3705 aOlA 

RESERVED aOlA 

RESERVED aOlA 

RECORD FORMAT 

OPTION CODE 

BLOCK LENGTH 

RECORD LENGTH 

KEY LENGTH 

RELATIVE KEY POSITION 

DATA SET INDICATORS 

SECONDARY ALLOCATION 

LAST USED TRACK AND BLOCK ON TRACK 

BYTES REMAINING ON LAST TRACK USED 

RESERVED 

FIRST EXTENT DESCRIPTION 

EXTENT TYPE INDICATOR 

EXTENT SEQUENCE NUMBER 

LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 

THIRD EXTENT DESCRIPTION 

POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 

LENGTH OF DSCB 
PARAMETER LIST 
ADDRESS OF CCHHR TO START SEARCH 

BUFFER ADDRESS 

ADDRESS OF CCHHR FIELD 

BYTE 

LAST DOUBLE WORD 

3 BYTE ADDRESS OF CCHHR 

NEXT DOUBLEWORD 






XXXXXXXXXXXXXXXXXXXXXXXXKXXKXXXXXXXXXXXXXXXMXXXMXXKXXXXXKXMM 



CVPL 


CVAFSEQ ACCESS=GT, 








BUFLIST=BFLHDR, 


ADDRESS OF BUFFER LIST 






MF=L 




+ 


CHOP 


0,4 




+CVPL 


EQU 


X 




+ 


DC 


CL4»CVPL' 


EBCDIC 'CVPL* 


+ 


DC 


AL2(ICV6E-CVPL) 


LENGTH OF CVPL 


+ 


DC 


XL1»04» 


FUNCTION CODE 


+ 


DC 


XL1»00» 


STATUS INFORMATION 


+ 


DC 


B'OOIOOOOO' 


FIRST FLAG BYTE 


+ 


DC 


B*00000000> 


SECOND FLAG BYTE 






,y 
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+ 


DC 


H'O' 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(BFLHDR) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ 


DC 


A(0) 


+ICV6E 


EQU 


X 




ORG 


CVPL 



CVPLMAP ICVAFPL DSECT=NO 



RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 
EXPAND MAP OVER LIST 
CVPL MAP 



+x CVAF PARAMETER LIST 



Jf**\, 



+CVPLMAP 


DS 


OF 


+CVLBL 


DS 


CL4 


+CVLTH 


DS 


H 


+CVFCTN 


DS 


XLl 


+CVDIRD 


EQU 


X'Ol' 


+CVDIWR 


EQU 


X'02' 


+CVDIRLS 


EQU 


X'03' 


+CVSEQGT 


EQU 


X'O^' 


+CVSEQGTE 


EQU 


X'05» 


+CVDMIXA 


EQU 


X»06' 


+CVDMIXD 


EQU 


X'07» 


+CVDMALC 


EQU 


X»08' 


+CVDMRLS 


EQU 


X'09' 


+CVDMMAP 


EQU 


X'OA* 


+CVVOL 


EQU 


X'OB* 


+CVVRFRD 


EQU 


X»OC» 


+CVVRFWR 


EQU 


X»OD' 


+CVSTAT 

+ 

+CVFL1 


DS 


XLl 


DS 


XLl 


+CV1IVT 


EQU 


X'80» 


+CV1I0AR 


EQU 


X'40' 


+CV1PGM 


EQU 


X»20» 


+CV1MRCDS 


EQU 


X'lO' 


+CV1IRCDS 


EQU 


X»08' 


+CV1MAPIX 


EQU 


X»04' 


+CV1MAPVT 


EQU 


X'02' 


+CV1MAPVL 


EQU 


X'Ol' 


+CVFL2 


DS 


XLl 


+CV2HIVIE 


EQU 


X»80» 


+CV2VRF 


EQU 


X»40* 


+CV2CNT 


EQU 


X»20' 


+CV2RCVR 


EQU 


XUO' 


+CV2SRCH 


EQU 


X'08' 


+CV2DSNLY 


EQU 


X»04» 


+CV2VER 


EQU 


X'02' 


+CV2NLEVL 


EQU 


X'01» 


+x 






+ 


DS 


H 


+CVUCB 


DS 


A 


+CVDSN 


DS 


A 


+CVBUFL 


DS 


A 


+CVIRCDS 


DS 


A 


+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 



CVAF PARAMETER LIST 

EBCDIC »CVPL' 

LENGTH OF CVPL 

FUNCTION BYTE 

CVAFDIR ACCESS=READ 

CVAFDIR ACCESS=WRITE 

CVAFDIR ACCESS=RLSE 

CVAFSEQ ACCESS=GT 

CVAFSEQ ACCESS=GTEQ 

CVAFDSM ACCESS=IXADD 

CVAFDSM ACCESS=IXDLT 

CVAFDSM ACCESS=ALLOC 

CVAFDSM ACCESS=RLSE 

CVAFDSM ACCESS=MAPDATA 

CVAFVOL ACCESS=VIBBLD 

CVAFVRF ACCESS=READ 

CVAFVRF ACCESS=WRITE 

STATUS INFORMATION (SEE LIST 

BELOUI) 

FIRST FLAG BYTE 

INDEXED VTOC ACCESSED 

IOAREA=KEEP 

BRANCH=(YES,PGM) 

MAPRCDS=YES 

IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 

SECOND FLAG BYTE 

HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 

CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 

MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
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+CVEXTS 
+CVBUFL2 
+CVVRFDA 
+CVCTAR 



DS 
DS 
DS 
DS 



EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



+CVPLNGTH EQU x-CVPLMAP 



+M VALUES OF CVSTAT 

+X(THIS PART OF THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
END 



EXAMPLE 5t USING THE CVAFTST AND CVAFDSH MACROS 



This example returns a format-5 DSCB to the caller. The 
format-5 DSCB is constructed by this program if the volume 
contains an indexed VTOC. The format-5 DSCB is read by another 
program^ F5RTN (not described in the example) » if the volume 
contains a nonindexed VTOC. 

The CVAFTST macro is used to determine if a nonindexed VTOC is 
on the volume. 

If the CVAFTST return code is neither nor 4 (a nonindexed VTOC 
is on the volume) » the CVAFDSM macro is issued to obtain up to 
27 extents from the VPSM in the VTOC index. The program does 
not determine whether the CVAFTST return code is 8 (volume 
contains indexed VTOC) or 12 (it cannot be determined what type 
of VTOC is on the volume). In either case> the CVAFDSM macro is 
issued. If the CVAFTST return code is 12, the CVAFDSM macro 
call Mill cause CVAF to determine whether an indexed or a 
nonindexed VTOC is on the volume, and the CVIIVT bit will be set 
to one or zero, accordingly. 

The extent table (at label EXTABL) is initialized to request 27 
extents from the CVAFDSM macro, which is one more than the 
number of extents that fit in a format~5 DSCB. The format-5 
DSCB is constructed from the first 26 extents returned from the 
CVAFDSM call. 

The first extent in the extent table is initialized from the 
last extent in the format-5 DSCB area supplied by the caller of 
the program. If this is the first call, the program assumes 
that the format-5 area is initialized to zero. Thus, the first 
extent in the extent table has a value of zero to serve as the 
starting place for the extent search. If this is the second or 
subsequent call, the last extent in the format-5 area would be 
the last extent obtained from the previous CVAFDSM call. 

The format-5 chain pointer field (DS5PTRDS) is set to a nonzero 
value if CVAFDSM returned a 27th extent. In this case, the 
program will be called again to obtain another format-5 DSCB. 

The program's return code is if no errors were encountered and 
4 if an error was encountered. 

This program must be APF authorized. 






o 
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EXAMPLES CSECT 

STM 1^,12,12(13) 

BALR 12,0 

USING )<,12 

ST 13,SAVEAREA+<i 

LA RWORK,SAVEAREA 

ST RW0RK,8(,13) 

LR 13,RU0RK 

X REGISTERS 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
RDEB EQU 3 
RUCB EQU 4 
RF5 EQU 5 



RUIORK 
REGIS 
X 

KFS 
xxxxxxxx 

X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 

xxxxxxxx 



+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ICV1E 



xxxxxxxx 

X 
X 
X 

xxxxxxxx 



EQU 
EQU 



6 

IS 



DEB ADDRESS SUPPLIED BY CALLER 

UCB ADDRESS SUPPLIED BY CALLER 

ADDRESS OF FORMAT S BUFFER SUPPLIED 

BY CALLER 

WORK REGISTER 

RETURN CODE REGISTER 15 



EQU 26 NUMBER OF FORMAT S EXTENTS 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

READ FORMAT 5 DSCB OR BUILD A f-URMAT 5 DSCB IF 

AN INDEXED VTOC 
UCB ADDRESS SUPPLIED IN RUCB. 
RF5 CONTAINS THE ADDRESS OF THE FORMAT S DSCB BUFFER. IT 

CONTAINS THE LAST FORMAT 5 DSCB READ OR BUILT. THE FORMAT 5 

BUFFER IS ZERO IF THIS IS THE FIRST CALL 
IF THE FORMAT S DSCB BUFFER RETURNED TO THE CALLER HAS A 

NONZERO VALUE IN DS5PTRDS, THIS ROUTINE WILL BE CALLED 

AGAIN TO OBTAIN THE NEXT FORMAT 5 DSCB. 



xxxxxxxxxxxxxxxxxxxx 
USING IECSDSF5,RFS 
CVAFTST UCB=(RUCB) 
CHOP 0,4 
LR 1,RUCB 
L 15,16 
L 15,328(,15) 
L 15,12(,15) 
LTR 15,15 
BZ ICVIE 
L 15,<i(,15) 
BALR 14,15 
EQU X 

LTR REGIS, REGIS 
BZ UNINDXD 
C REGIS, NOTIXRC 
BE UNINDXD 



xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

ADDRESSABILITY TO FORMAT 5 BUFFER 
TEST VTOC 

START OF CVAFTST MACRO 

LOAD PARAMETER REG 1 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVAF TABLE ADDRESS 
TEST FOR ZERO VALUE 
CVAF IS NOT ON THE SYSTEM 
LOAD POINTER TO CVAF TEST E.P. 
BRANCH AND LINK TO CVAF TEST 
END OF CVAFTST 



READ NEXT FORMAT 5 
UNINDEXED VTOC? 
READ NEXT FORMAT 5 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



ASSUME INDEXED VTOC UNLESS CVAFDSM CALL INDICATES UNINDEXED 



xxxxxxxxxxxxxxxxxxxxxx 
MVC EXTS(L'DS5AVEXT) 



CVAFDSM MF=(E,CVPL), 
UCB=(RUCB), 
DEB=(RDEB), 

BRANCH=YES 
LA 1,CVPL 
L 15,16 
L 15,328(,15) 
L 15,12(,15) 
L 15,0(,1S) 
BALR 14,15 
TM CVFL1,CV1IVT 
BZ UNINDXD 
LTR REGIS, REGIS 
BZ NOERROR 
C REGIS, RC04 



xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
,DS5MAVET+L'DS5MAVET-L'DSSAVEXT MOVE THE X 
LAST EXTENT FROM FORMAT 5 TO FIRST X 
ENTRY IN THE EXTENT TABLE 
GET 27 EXTENTS FROM CVPL X 

RUCB ADDRESS REQUIRED X 

RDEB ADDRESS REQUIRED BY X 

UNAUTHORIZED PROGRAMS CALLING CVAF X 
BRANCH ENTRY CALL x 

LOAD PARAMETER REG 1 
LOAD THE CVT 

LOAD VS1/VS2 COMMON EXTENSI0N2 
LOAD THE CVAF TABLE ADDRESS 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 
IS THIS INDEXED VTOC 
READ FORMAT 5 IF NOT 
ANY ERROR 
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BNE OTHERERR 

CLI CVSTAT,STAT032 

BNE OTHERERR 

NOERROR EQU ^ 

MVC DS5KEYID,F5ID 



UNEXPECTED ERROR 
END OF DATA 
UNEXPECTED ERROR 
BUILD FORMAT 5 



> 



UNINDXD 



MVC DS5AVEXT(L'DS5AVEXT+L'DS5EXTAV),EXTS MOVE IN EXTENTS X 

TO DS5FMTID 
MVI DS5FMTID,C»5» 
MVC DS5MAVET,EXTS+L'DS5AVEXT+L'DS5EXTAV MOVE REMAINING X 

EXTENTS 
XR REGIS, REGIS RETURN CODE ZERO 

XC DS5PTRDS,DS5PTRDS ZERO CHAIN POINTER 
NC EXTS+L • EXTS-L ' DSSAVEXTC L ' DSSA VEXT ) , EXTS+L » EXTS-L ' DS5AVEXTM 

IS LAST(27TH) EXTENT FROM CVAF X 

ZERO? 
BZ RETURN BRANCH IF YES-LEAVE DSSPTRDS ZERO 

MVI DS5PTRDS+L'DSSPTRDS-1,1 SET DSSPTRDS NONZERO TO SIMULATE X 

THERE BEING ANOTHER FORMAT 5 
B RETURN 
EQU X 



LINK EP=FSRTN 



RETURN 



0,4 

lS,x+20 

A(x+8) 

A(0) 

CLS'FSRTN' 

6 

E 

13,SAVEAREA+4 



CHOP 

BAL 

DC 

DC 

DC 

SVC 

EQU 

L 

RETURN (14,12),RC=(15) 



OTHERERR 



DSCB 

+IECSDSL5 

+IECSDSFS 

+DS5KEYID 

+DSSAVEXT 

+x 

+x 

+x 

+x 

+DS5EXTAV 

+DSSFMTID 

+DS5MAVET 

+DS5PTRDS 

+DSSEND 

EXAMPLES 

NOTIXRC 

RC04 

F5ID 

SAVEAREA 

EXTABL 

EXTNO 

EXTS 

CVPL 



14,12(13,0) 
0,12,20(13) 
14 

REGIS, RC04 
RETURN 



L 

LM 

BR 

EQU 

L 

B 

DSECT 

lECSDSLl (S) 

EQU 

EQU 

DS 

DS 

BYTES 



CALL ROUTINE TO READ NEXT FORMAT 5 
LINK TO FORMAT 5 ROUTINE. RETURN J 
CODE PASSED BACK IN REGIS 

LOAD SUP.PARAMLIST ADR 
ADDR OF EP PARAMETER 
DCB ADDRESS PARAMETER LCOA 
EP PARAMETER 
ISSUE LINK SVC 
RETURN TO CALLER 



RESTORE REGISTER 14 
RESTORE THE REGISTERS 
RETURN 

ERROR 

ERROR RETURN CODE 






FORMAT S DSCB 



lECSDSLS 
XL4 
XLS 
1-2 



BYTES 3 - 
BYTE S 



DS 

DS 

DS 

DS 

EQU 

CSECT 

DC 



XL3S 

CLI 

XL90 

XLS 

X 



KEY IDENTIFIER 
AVAILABLE EXTENT 

RELATIVE TRACK ADDRESS OF THE FIRST TRACK 

IN THE EXTENT 

NUMBER OF UNUSED CYLINDERS IN THE EXTENT 

NUMBER OF ADDITIONAL UNUSED TRACKS 
SEVEN AVAILABLE EXTENTS 
FORMAT IDENTIFIER 
EIGHTEEN AVAILABLE EXTENTS 
POINTER TO NEXT FORMAT S DSCB 



DC 
DC 
DS 
DS 
DC 
DS 



F»4» 

F»4* 

XL4'0S0S0S0S0S» 

18F 



CVAFTST RETURN CODE-UNINDEXED 
RETURN CODE 4 
FORMAT S FIELD, DSSKEYID 
REGISTER SAVE AREA 

0CL(1+(KFS+1)XL»DS5AVEXT) EXTENT TABLE 

AL1(KF5+1) NUMBER OF EXTENTS IN TABLE 

CL((KFS+1)XL»DSSAVEXT) EXTENTS 
CVAFDSM ACCESS=MAPDATA, 

COUNT=NO, DO NOT COUNT EXTENTS 

ACCESS VOLUME SPACE MAP 
EXTENT TABLE ADDRESS 
LIST FORM OF MACRO 



CHOP 



MAP=VOLUME, 

EXTENTS=EXTABL, 

MF=L 

0,4 






y 
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+ CVPL 


EQU 


X 




+ 


DC 


CL4'CVPL' 


EBCDIC 'CVPL' 


+ 


DC 


AL2(ICV9E-CVPL) 


LENGTH OF CVPL 


+ 


DC 


XLl'OA' 


FUNCTION CODE 


+ 


DC 


XLl'OO' 


STATUS INFORMATION 


+ 


DC 


B*00100001* 


FIRST FLAG BYTE 


+ 


DC 


B*00000000' 


SECOND FLAG BYTE 


+ 


DC 


H'O' 


RESERVED 


+ 


DC 


A(0) 


UCB ADDRESS 


+ 


DC 


A(0) 


DATA SET NAME ADDRESS 


+ 


DC 


A(0) 


BUFFER LIST ADDRESS 


+ 


DC 


A(0) 


INDEX VIR'S BUFFER LIST ADDRESS 


+ 


DC 


A(0) 


MAP VIR'S BUFFER LIST ADDRESS 


+ 


DC 


A(0) 


I/O AREA ADDRESS 


+ 


DC 


A(0) 


DEB ADDRESS 


+ 


DC 


A(0) 


ARGUMENT ADDRESS 


+ 


DC 


A(0) 


SPACE PARAMETER LIST ADDRESS 


+ 


DC 


A(EXTABL) 


EXTENTS TABLE ADDRESS 


+ 


DC 


A(0) 


NEW VRF VIXM BUFFER LIST ADDR 


+ 


DC 


A(0) 


VRF DATA ADDRESS 


+ 


DC 


A(0) 


COUNT AREA ADDRESS 


+ICV9E 


EQU 


X 


END OF CVPL 




ORG 


CVPL 


OVERLAY CVPL WITH EXPANSION OF MAP 


CVPLMAP 


ICVAFPL DSECT=NO 




+ XXXXXXXXXXXX)«XXXKXXKXJ()(XJ(XXXXXXXXXXXXXXXXXX)(XXMXXKXXXXXXXXXXX)(XXXXXXXXX 


•fX 


CVAF 


PARAMETER LIST 




+XXXXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXXX 


+CVPLMAP 


DS 


OF 


CVAF PARAMETER LIST 


+CVLBL 


DS 


CL4 


EBCDIC 'CVPL' 


+CVLTH 


DS 


H 


LENGTH OF CVPL 


+CVFCTN 


DS 


XLl 


FUNCTION BYTE 


+CVDIRD 


EQU 


X'Ol' 


CVAFDIR ACCESS=READ 


+CVDIWR 


EQU 


X»02' 


CVAFDIR ACCESS=WRITE 


+CVDIRLS 


EQU 


X»03» 


CVAFDIR ACCESS=RLSE 


+CVSEQGT 


EQU 


X»04' 


CVAFSEQ ACCESS=GT 


+CVSEQGTE 


EQU 


X'05' 


CVAFSEQ ACCESS=GTEQ 


+CVDMIXA 


EQU 


X'06' 


CVAFDSM ACCESS=IXADD 


+CVDMIXD 


EQU 


X'07» 


CVAFDSM ACCESS=IXDLT 


+CVDMALC 


EQU 


X»08» 


CVAFDSM ACCESS=ALLOC 


+CVDMRLS 


EQU 


X'09' 


CVAFDSM ACCESS=RLSE 


+CVDMMAP 


EQU 


X'OA» 


CVAFDSM ACCESS=MAPDATA 


+CVVOL 


EQU 


X'OB' 


CVAFVOL ACCESS=VIBBLD 


+CVVRFRD 


EQU 


X'OC* 


CVAFVRF ACCESS=READ 


+CVVRFWR 


EQU 


X'OD' 


CVAFVRF ACCESS=WRITE 


+CVSTAT 


DS 


XLl 


STATUS INFORMATION (SEE LIST X 


+ 






BELOW) 


+CVFL1 


DS 


XLl 


FIRST FLAG BYTE 


+CV1IVT 


EQU 


X»80» 


INDEXED VTOC ACCESSED 


+CV1I0AR 


EQU 


X*40' 


IOAREA=KEEP 


+CV1PGM 


EQU 


X'20' 


BRANCH=(YES,PGM) 


+CViriRCDS 


EQU 


XUO' 


MAPRCDS=YES 


+CV1IRCDS 


EQU 


X'08» 


IXRCDS=KEEP 


+CV1MAPIX 


EQU 


X'O'i' 


MAP=INDEX 


+CV1MAPVT 


EQU 


X'02' 


MAP=VTOC 


+CV1MAPVL 


EQU 


X'Ol' 


MAP=VOLUME 


+CVFL2 


DS 


XLl 


SECOND FLAG BYTE 


+CV2HIVIE 


EQU 


X'80' 


HIVIER=YES 


+CV2VRF 


EQU 


X»40» 


VRF DATA EXISTS 


+CV2CNT 


EQU 


X»20' 


COUNT=YES 


+CV2RCVR 


EQU 


X'lO' 


RECOVER=YES 


+CV2SRCH 


EQU 


X»08' 


SEARCH=YES 


+CV2DSNLY 


EQU 


X»0^' 


DSNONLY=YES 


+CV2VER 


EQU 


X'02» 


VERIFY=YES 


+CV2NLEVL 


EQU 


X'Ol' 


OUTPUT-NEW HIGHEST LEVEL VIER 


+x 






CREATED 


+ 


DS 


H 


RESERVED 


+CVUCB 


DS 


A 


UCB ADDRESS 


+CVDSN 


DS 


A 


DATA SET NAME ADDRESS 


+CVBUFL 


DS 


A 


BUFFER LIST ADDRESS 


+CVIRCDS 


DS 


A 


INDEX VIR'S BUFFER LIST ADDRESS 
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+CVMRCDS 


DS 


A 


+CVIOAR 


DS 


A 


+CVDEB 


DS 


A 


+CVARG 


DS 


A 


+CVSPACE 


DS 


A 


+CVEXTS 


DS 


A 


+CVBUFL2 


DS 


A 


+CVVRFDA 


DS 


A 


+CVCTAR 


DS 


A 


+CVPLNGTH 


EQU 


X-CVPLMAP 


+x 




VALUES OF CVSTAT 


+X(THIS PART OF 


THE ICVAFPL MACRO 




END 





MAP VIR'S BUFFER LIST ADDRESS 

I/O AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 

EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 

VRF DATA ADDRESS 

COUNT AREA ADDRESS 



EXPANSION IS NOT SHOWN) 
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APPENDIX C, RETURN CODES FROM VTOC ACCESS MACROS 



RETURN CODES FROM THE CVAFDIR MACRO 



On return from CVAF, register 1 contains the address of the CVAF 
parameter list (CVPD* and register 15 contains one of the 
following return codes! 



^**^\ 
^^,»>^ 



Code 

0(00) 



4(04) 



8(08) 



12(0C) 



16(10) 



Meaning 

The request Mas successful. HoMever» if the CVAFDIR 
request is to read or Mrite a DSCB and a VTOC index 
structure error is encountered^ the CVSTAT field 
indicates the structure error encountered. (CVSTAT 
code descriptions are in Appendix B.) 

An error occurred. The CVSTAT field in the CVPL 
contains an indication of the cause of the error, 
(CVSTAT code descriptions are in Appendix B.) 

Invalid VTOC index structure Mhile processing a request 
to read or write a VTOC index record. The CVSTAT field 
in the CVPL contains an indication of the cause of the 
error. (CVSTAT code descriptions are in Appendix B.) 



The CVAF parameter list is not 
is invalid (the ID is invalids 
incorrect, or the CVFCTN field 
has not been modified. 

An I/O error was encountered. 



in your protect key, or 
or the length field is 
is invalid). The CVPL 



RETURN CODES FROM THE CVAFDSM MACRO 



On return from CVAF, register 1 contains the address of the CVAF 
parameter list (CVPL), and register 15 contains one of the 
following return codes: 



Code 

0(00) 

4(04) 

8(08) 
12(0C) 



Meaning 

The request was successful. 

End of data (CVSTAT is set to decimal 32), or an error 
was encountered. The CVSTAT field in the CVPL contains 
an indication of the cause of the error. (CVSTAT code 
descriptions are in Appendix B.) 

Invalid VTOC index structure. CVSTAT contains an 
indication of the cause of the error. (CVSTAT code 
descriptions are in Appendix B.) 



The CVAF parameter list is not 
is invalid (the ID is invalid, 
incorrect, or the CVFCTN field 
has not been modified. 



in your protect key, or 
or the length field is 
is invalid). The CVPL 



16(10) An I/O error was encountered. 



o 
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RETURN CODES FROM THE CVAFSEQ MACRO 



On return from CVAF» register 1 contains the address of the CVAF 
parameter list (CVPL)» and register 15 contains one of the 
following return codes* 

Code Meaning 

0(00) The request Mas successful. 

4(04) End of data (CVSTAT is set to decimal 32) » or an error 
Mas encountered. The CVSTAT field in the CVPL contains 
an indication of the cause of the error. Error 
descriptions are in Appendix D. 

8(08) Invalid VTOC index structure. CVSTAT contains an 
indication of the cause of the error. Error 
descriptions are in Appendix D. 

12(0C) The CVAF parameter list is not in your protect key# or 
is invalid (the ID is invalids or the length field is 
incorrect, or the CVFCTN field is invalid). The CVPL 
has not been modified. 

16(10) An I/O error Mas encountered. 



RETURN CODES FROM THE CVAFTST MACRO 



On return from CVAF, register 15 contains one of the folloMing 
return codes: 

Code Meaning 

0(00) The system does not support an indexed VTOC. The 

volume should be considered to have an nonindexed VTOC. 
The UCB Mas not inspected to determine its validity or 
status. 

4(04) The system supports an indexed VTOC» but the volume has 
an nonindexed VTOC. 

8(08) The system supports an indexed VTOC and the volume has 
an indexed VTOC. 

12(0C) The system supports an indexed VTOC, but the volume is 
not mounted or the VIB is not initialized for it, so 
the status (indexed or nonindexed) of the VTOC can not 
be determined. 

16(10) The system supports an indexed VTOC, but the unit is 
not a DASD or has a VIO UCB, or the UCB address is 
invalid. 



■<4 jf' 
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APPENDIX D. VTOC ERROR MESSAGE AND ASSOCIATED CODES 



ERROR riES?AGIg 



EXPLANATION 



SYSTEN ACTION 



Uhen CVAF finds an error in a VTOC index» it issues this 
message: 

IEC606I VTOC INDEX DISABLED ON dev»volser, 
code» [rbaC >secno> offset]] 

In addition^ CVAF puts a return code in the CVSTAT field of the 
CVPL. 



The Common VTOC Access Facility (CVAF) detected a VTOC index 
error on the device 'dev' with volume serial number *volser'. 
'code* is a number that represents the kind of VTOC index error 
encountered. These codes and their meanings are in Appendix C. 
•rba* is the RBA of the VIR in the VTOC index that contains a 
structure error indicated by 'code'. If the VIR is a VIER» the 
section number in the VIER containing the VTOC index entry is 
supplied in 'secno', and the offset into the section of that 
VTOC index entry is supplied in 'offset'. 



The VTOC index is disabled by zeroing the index bit in the 
format-4 DSCB and setting the bit in the first high-level VIER 
Mhich indicates invalid VTOC index structure. The VTOC Mill be 
converted to nonindexed format Mhen DADSM next allocates space 
on the volume. A system dump is written to the SYSl.DUMP data 
set» and an entry is made in the SYSl.LOGREC data set. The 
message IEC604I (which indicates that the VTOC convert routines 
have been used) will be issued later. 



PR06RANNER RESPONSE 



Examine the system dump and a print of the VTOC index* and use 
the information in message IEC606I to determine the cause of the 
VTOC index structure error. 



ROUTING AND DESCRIPTOR CODES 



The routing codes are 4 (direct access pool) and 10 
(system/error maintenance) » and the descriptor code is 4 (system 
status) . 



CODES PUT IN THE CVSTAT FIELD 

Code Meaning 

0(00) 

1(01) 

2(02) 



No error. 

Data set name not found. 



Argument is outside VTOC extents or RBA range of VTOC 
index. 

4(04) Invalid parameter supplied (wrong key). 

5(05) DSN keyword omitted. 
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code Meaning 

6(06) Not authorized to perform this function. 

7(07) Buffer list omitted. 

8(08) DEB invalid or omitted or not open to VTOC. 

9(09) IOAREA=KEEP and user not authorized* or I/O area 
supplied and user not authorized 

lO(OA) Function not supported on indexed VTOC. 

ll(OB) DSCB is not format-0 DSCB and VERIFY=YES, 

12(0C) MAPRCDS=YES and/or IXRCDS=KEEP but VTOC is nonindexed. 

13(0D) IXRCDS=KEEP not specified for CVAFDSM ACCESS=IXADD or 
IXDLT. 

14(0E) CTAREA keyword omitted. 

15(0F) UCB invalid* volume not mounted; VIO unit, not DASD. 

17(11) DSCB length invalid for the function requested: 96 

bytes for CVAFDIR ACCESS=WRITE, VERIFY=YES; 96 bytes for 
CVAFSEQ reading in data-set-name sequence; 140 bytes 
for CVAFSEQ reading in physical sequence. 

19(13) UCB omitted and CVAF I/O area not supplied. 

22(16) Data set name already supplied. 

23(17) Invalid DSN supplied (44X*FF» is a reserved data set 
name). 

24(18) ARG keyuiord not supplied. iTx 

25(19) Conflicting or incomplete information specified in the '^--^ 
space table for a CVAFDSM ACCESS=ALLOC, MAP=VOLUME 
request. 

27(1B) VTOC index full. No free VIRs available and a VIER 
split is required. 

28(1C) Space keyword omitted (CVSPACE field zero in CVPL). 

29(1D) CVAFDSM ACCESS=ALLOC: No format DSCB available 

(MAP=VTOC), or VTOC index full (MAP=INDEX), or volume 
space not available (MAP=VOLUME) . 

30(1E) CVAFDSM ACCESS=ALLOC: CCHHR (MAP=VTOC) or RBA 

MAP=INDEX or volume space extent (MAP=VOLUME) already 
allocated. 

31(1F) CVAFDSM ACCESS=ALLOC: CCHHR supplied outside VTOC 

extents (MAP=VTOC), or RBA outside VTOC index extents 

(MAP=INDEX)» or volume space extent invalid or outside 
volume (MAP=VOLUME). 

32(20) End of data. CVAFDSM ACCESS=MAPDATA: no more free 

extents in VPSM. CVAFSEQ* no more names in index or 
DSCBs in VTOC. For indexed access* no DSN in VTOC index 
with higher or higher-or-equal key than that supplied. 
For physical-sequential access* no DSCB in the VTOC has 
a higher argument than that supplied. For a multiple 
DSCB request* the last DSCB in the VTOC was read and 
more DSCBs were requested. 



33(21) EXTENTS keyword omitted* or supplied number of extents 
is zero. 
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o 



Code Meaning 

3^(22) CVAFDSM ACCESS=RLSE1 format DSCB already free 

(MAP=VTOC), or VIER already unallocated (MAP=INDEX) or 
volume space extent already unallocated (MAP=VOLUME) . 

42(2A) VRF data supplied for write too long. 

43(2B) Buffer list is for VIRs, but a DSCB buffer list is 
requi red. 

44(2C) No buffer list entry found. 

45(2D) Invalid DSCB buffer length (neither 96 nor 140) in 

buffer list entry* or VIR buffer length not equal to 
VIB VIR size. 

46(2E) Neither TTR nor CCHHR bits set in buffer list entry to 
be used in writing a 140~byte DSCB. 

47(2F) More than one of the TTR, CCHHR, and RBA bits set in 
the buffer list entry. 

48(30) Both the DSCB and VIR bits set in the buffer list 
header. 

49(31) RBA bit set in a buffer list entry for a DSCB buffer 
list. 

50(32) TTR or CCHHR bit set in buffer list entry but buffer 
list header indicates buffer list is for a VIR. 

52(34) Combination of MAP and COUNT not supported. 

53(35) MAP omitted. 

54(36) Buffer list for a VIR chained to or from a buffer list 
for a DSCB. 

55(37) Unauthorized caller and VIB not initialized. 

56(38) MAPRCDS=YES not specified but required. 

57(39) Buffer list for a DSCB supplied but buffer list for a 
VIR required (in MAPRCDS or IXRCDS buffer list address 
in CVAF parameter list). 

58(3A) Neither the VIR nor DSCB bit set in a buffer list 
header. 

60(3C) Invalid or conflicting setting of allocate option byte 
in space parameter 

127(7F) I/O error occurred. 

128(80) Reserved. 

129(81) The first high-level VIER as indicated in the VIXM does 
not have the flag bit set indicating it is the first 
high-level VIER. 

130(82) A horizontal or vertical VIER pointer is outside the 
RBA range of the VTOC index. 

131(83) A vertical VIER pointer points to a VIR which is not a 
VIER (invalid ID in header). 

132(84) A level n vertical index entry pointer points to a VIER 
which is not at level n-1. 



Appendix D. VTOC Error Message and Associated Codes 225 



Code Heaning 

133(85) Level n horizontal index entry pointer points to VIER 
Mhich is not at level n. 

134(86) Horizontal VIER/map pointer points to a VIR uhich is 
not a VIER/map (invalid ID in header). 

135(87) Horizontal map pointer points to VIR which is not one 
of the first n VTOC index records (n is recorded in 
VIXM field VIMRCDS), or the first record in the VTOC 
index is not a VIXM. 

136(88) A level-1 index entry contains a CCHHR pointer which is 
outside the VTOC extent. 

137(89) The first high-level VIER, as indicated in the VIB, 
does not have the flag bit set indicating it is the 
first high-level VIER. (This error is either recovered 
from by updating the VIB from the VIXM» or the error is 
changed to 129.) 

138(8A) The RBA of the VTOC index VIR does not match the RBA 
recorded in the header of the record. 

139(8B) The first record of a map (VIXM, VPSM, or VMDS) is not 
one of the first n VTOC index records (n is recorded in 
the VIXM field, VIMRCDS). 

140(80 The data set name in a level n+1 VIER entry is lower 
than the high key of the level n VIER that the level 
n+1 VIER entry points to. 

141(8D) First high-level VIER structure error bit is on. 

142(8E) I/O error indicating the VTOC index is not formatted 

correctly. f^ ^ 



143(8F) Either the index bit is zero or the DOS bit is zero in 
the format-4 DSCB of a VTOC previously found to be an 
indexed VTOC. 

144(90) No SYSl.VTOCIX.nnn data set name in a VTOC whose 

format-4 DSCB has the index bit on, indicating the VTOC 
has an index. 

145(91) The data set name in a level n-f-l VIER entry is higher 
than the high key of the level n VIER that the level 
n+1 VIER entry points to 

146(92) Four or more high-level VIERs were encountered. 

147(93) Too many levels in the VTOC index. The length of the 
search list was exceeded. 

148(94) VIER invalid, because offset to last section is 
invalid. 

149(95) VIER invalid, because offset to last entry in a section 
is invalid. 

150(96) Media Manager initialization failed. 

151(97) Level-2 or higher VIER contains fewer than two entries. 

152(98) RECOVER=YES specified but the static text module 
(ICVIXSTO) indicates recovery is not permitted. 



^4 gj^ 



226 MVS/370 System Programming Library? Data Management 



code Heaning 

153(99) The format-4 DSCB on an indexed VTOC is written Mith 

either the index- or DOS-bit zeroed on an indexed VTOC. 

154(9A) A space map extends over more than 10 VTOC index 
records. 

155(9B) Data set name not found in section Mith key greater 

than or equal to the name being searched for. The VIER 
section containing the name is invalid. 

156(9C) Invalid VIER horizontal pointer. Horizontal pointer of 
VIERl points to VIER2 Mhose high key is loMer than or 
equal to the high key of VIERl. 

157(9D) Could not find entry in level-2 or higher VIER that 
matches the high key of the VIER. 

158(9E) Invalid section length or invalid number of sections in 
a VIER header. 

159(9F) The first high-level VIER pointed to by the VIB has an 
invalid ID in the header. 
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APPENDIX E. EXAMPLE OF AN OPEN EXIT HODULE 



PROCESSING IN IFGOEXOB 



The folloMing program listing is a sample of IFGOEXOB. The four 
subroutines (BUFNO, SCREEN, RLSE, and SQTY) show examples of the 
kind of processing that can be done in your installation's 
version of IFGOEXOB. 

The BUFNO subroutine defaults the number of buffers for QSAM 
DCBs (DCBBUFNO) if the value is zero when the exit is given 
control. The block size in the DCB (DCBBLKSI) is used, together 
with a fixed amount of storage (64K bytes in the example) to 
determine a buffer number. A buffer number is limited to a 
fixed value (32 in the example). Storage quantity and maximum 
buffer number Qre contained in two tables, DAMAX and TPMAX, 
which are used for DASD devices and tape devices, respectively. 
Storage quantity is expressed in units of 1024 (IK) bytes. The 
values in the DAMAX and TPMAX tables can be altered by your 
installation. 

The SCREEN subroutine determines those cases in which the 
succeeding subroutines, RLSE and SQTY, should be executed. DASD 
sequential and partitioned data sets being processed by BSAM or 
QSAM and opened for OUTPUT or OUTIN are selected.^ The VTOC data 
set and data sets start i^ng with 'SYSl.* (system data sets) are 
excluded. An installation may want to make further selection 
tests. 



REQUESTING PARTIAL RELEASE 



The RLSE subroutine sets on the partial release indicators in 
the JFCB if the number of extents in the data set is less than a 
fixed value (8 in the example). It sets off the partial release 
indicators in the JFCB if the number of extents in the data set 
is equal or greater than a fixed value (8 in the example). 
Partitioned data sets are not processed, because they may be 
opened many times to write one new member for each OPEN/CLOSE. 






UPDATING THE SECONDARY SPACE DATA 



The SQTY subroutine provides a default secondary space quantity 
if none is specified. The default is one half of the primary 
space quantity if it is greater than one. If the primary 
quantity is zero, secondary is set to a fixed default number of 
tracks (5 in the example). If the primary quantity is one, 
secondary is set to the same fixed default (5); note that, in 
this case, the secondary quantity is in units of tracks, 
cylinders, or average blocks, depending on the unit of the 
primary quantity. 

If the secondary space quantity is not zero, the SQTY subroutine 
tests the number of extents in the data set. If the number of 
extents is equal to or greater than a fixed value (10 in the 
example), then the secondary quantity is increased by 50% if it 
is greater than 1. It is set to a default quantity (5 in the 
example) if the secondary quantity is one; note that, in this 
case, the secondary quantity is in units of tracks, cylinders, 
or average blocks, depending on that of the primary quantity. 
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IFGOEXOB CSECT 



""X 



FUNCTION = 

FOUR SAMPLE ROUTINES ARE SUPPLIED. 



BUFNO - DEFAULT DCBBUFNO 

DCBBUFNO (NUMBER OF BUFFERS) 
OPENS TO PHYSICAL SEQUENTIAL 
ON DASD AND TAPE USING QSAM, 



IS DEFAULTED FOR 

AND PARTITIONED DATA SETS 

FOR WHICH DCBBUFNO IS ZERO. 



DCBBUFNO FOR SYSIN, SYSOUT, TERMINAL, AND DUMMY DATA SETS 
IS SET TO THE EQUATE, INOUTBNO, OR THE VALUE IN THE 
FULLWORD, INOUTBN. 

DCBBUFNO IS SET TO THE NUMBER OF DCBBLKSZ BUFFERS WHICH 

FIT IN A GIVEN AMOUNT OF STORAGE. THE AMOUNT OF STORAGE IS 

DEFINED BY THE EQUATES, DAMXK AND TPMXK (OR THE FULLWORDS 

AT LABELS, DAMAXK AND TPMAXK), FOR DASD AND 

TAPE, RESPECTIVELY. THE EQUATES DEFINE THE AMOUNT OF 

STORAGE FOR BUFFERS IN UNITS OF 1024 (IF DAMXK IS 32, THEN 

THE AMOUNT OF STORAGE IS 32K, OR 32768). 

DAMXK OR TPMXK TIMES 1024 IS DIVIDED BY DCBBLKSI TO 

DETERMINE THE NUMBER OF BUFFERS TO DEFAULT. 

THE EQUATES, DAMXBNO AND TPMXBNO, OR THE FULLWORDS 

AT LABELS, DAMAXBNO AND TPMAXBNO, 

DEFINE THE MAXIMUM NUMBER OF BUFFERS TO BE 

DEFAULTED FOR DASD AND TAPE IF THE CALCULATION, ABOVE, 

RESULTS IN A LARGER NUMBER. 

SCREEN - SCREEN OUT CASES FOR RLSE, SQTY 



RLSE - SET OR ZERO PARTIAL RELEASE 

THIS ROUTINE SETS PARTIAL RELEASE FOR DASD PS 
SETS BEING OPENED FOR OUTPUT OR OUTIN. 



(NOT PO) DATA 



PARTIAL RELEASE IS SET ON IF THE NUMBER OF EXTENTS IS LESS 
THAN A QUANTITY DEFINED BY THE EQUATE, RLSEl, OR THE BYTE, 
EXTRLSEl. 



EXTENTS IS NOT 
RLSEO, OR THE 



PARTIAL RELEASE IS SET OFF IF THE NUMBER OF 
LESS THAN A QUANTITY DEFINED BY THE EQUATE, 
BYTE, EXTRLSEO. 

SQTY - SET OR UPDATE SECONDARY SPACE QUANTITY 
THIS ROUTINE UPDATES THE SECONDARY SPACE 
QUANTITY FOR DASD PS OR PO DATA SETS BEING 
OPENED FOR OUTPUT OR OUTIN. 

IF THE SECONDARY QUANTITY IS NOT ZERO, 

AND IF THE NUMBER OF EXTENTS IN THE DATA SET IS 

AT LEAST EQUAL TO THE QUANTITY IN THE EQUATE, EXTSQT (OR 

THE BYTE AT LABEL, EXTSQTY), THEN: 

1. IF THE SECONDARY QUANTITY IS GREATER THAN ONE, 
SECONDARY QUANTITY IS INCREASED BY ONE HALF 
(50%). 

2. IF THE SECONDARY QUANTITY IS ONE, 

SECONDARY QUANTITY IS SET TO THE VALUE IN THE FULLWORD 
AT LABEL, SQTYDFLT (EQUAL TO THE EQUATE, SQTYDFL). 

IF THE SECONDARY QUANTITY IS NOT ZERO, 
AND IF THE NUMBER OF EXTENTS IN THE DATA SET IS 
LESS THAN THE QUANTITY IN THE EQUATE, EXTSQT (OR 
THE BYTE AT LABEL, EXTSQTY), SECONDARY QUANTITY 
IS LEFT UNCHANGED. 
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X 
IF SECONDARY QUANTITY IS ZERO, IT IS SET TO ONE HALF x 
OF PRIMARY QUANTITY IF PRIMARY IS NOT ZERO OR ONE. X 

IF PRIMARY QUANTITY IS ZERO, THE SPACE TYPE IS SET TO TRACKS, X 



'^\ 



OR DAMAX TABLES 
EVEN/ODD PAIR 



AND SECONDARY QUANTITY IS SET TO THE VALUE IN THE FULLWORD 
AT LABEL SQTYDFLT (EQUAL TO THE EQUATE, SQTYDFL). 
IF PRIMARY QUANTITY IS ONE, SECONDARY QUANTITY IS SET TO 
VALUE IN THE FULLWORD AT LABEL SQTYDFLT (EQUAL TO THE 
EQUATE, SQTYDFL). 

NOTES = SEE BELOW 

DEPENDENCIES = 

CLASS ONE CHARACTER CODE. THE EBCDIC CHARACTER CODE 
WAS USED FOR ASSEMBLY. THE MODULE MUST BE REASSEMBLED 
IF A DIFFERENT CHARACTER SET IS USED FOR EXECUTION. 

RESTRICTIONS = NONE 

REGISTER CONVENTIONS = 

Rl OIEXL ADDRESS 

R2 DCB ADDRESS 

R3 UCB ADDRESS 

R4 DCB BLOCK SIZE 

R5 ADDRESS OF TPMAX 

R6 EVEN REGISTER OF 

R7 ODD REGISTER OF EVEN/ODD PAIR 

R8 TIOT ENTRY ADDRESS 

R8 JFCB ADDRESS 

RIO FORMAT 1 DSCB ADDRESS 

Rll SAVE RETURN CODE 

R13 SAVE AREA ADDRESS 

R14 RETURN ADDRESS 

R15 BASE REGISTER 

PATCH LABEL = PATCH 

MODULE TYPE = CONTROL (OPEN, CLOSE, EOV DATA "MANAGEMENT) 

PROCESSOR = ASSEMBLER XF 

MODULE SIZE = SEE EXTERNAL SYMBOL DICTIONARY 

ATTRIBUTES = REENTRANT, REFRESHABLE, READ-ONLY, ENABLED, 
PRIVILEGED, SUPERVISOR STATE, KEY ZERO, 
LINK PACK AREA RESIDENT/PAGEABLE 

ENTRY POINT = IFGOEXOB 

PURPOSE = SEE FUNCTION 

LINKAGE = 

FROM IFG0196L: 
BALR 14,15 

INPUT = STANDARD LINKAGE CONVENTIONS 

OUTPUT = DCBBUFNO DEFAULTED 

PARTIAL RELEASE SET OR RESET 
CONTIGUOUS FLAG SET TO ZERO 
SECONDARY SPACE REQUEST MODIFIED 
RETURN CODE IN REGISTER 15 
IF JFCB NOT MODIFIED 
4 IF JFCB MODIFIED 






"fcliHui*'''^ 
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X EXIT-NORMAL = X 

X BR 1^ X 

X EXIT-ERROR = x 

X NONE X 

)( x 

X EXTERNAL REFERENCES = SEE BELOW X 

X X 

X ROUTINES = NONE x 

X X 

X DATA AREAS = NONE X 

X X 

X CONTROL BLOCK = NONE X 

X X 

X TABLES = NONE x 

X X 

X MACROS = MODESET, lECOIEXL, IHADCB, lEFUCBOB, lEFTIOTl, lEFJFCBN, X 

X lECSDSLl X 

X X 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X REGISTER EQUATES 
X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



Rl 

RDCB 

RUCB 

RBKSIZ 

RMAX 

REVEN 

ROOD 



EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 



RTIOT 

RJFCB 

RDSCB 

RINCODE 

R12 

RSAVE 

RET 

RCODE 



EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 



OIEXL PARAMETER LIST ADDRESS 

DCB ADDRESS 

UCB ADDRESS 

DCB BLOCK SIZE 

ADDRESS OF TPMAX OR DAMAX 

EVEN REGISTER OF EVEN/ODD PAIR 

ODD REGISTER OF EVEN/ODD PAIR. HAS 

DCBBUFNO DEFAULT 

TIOT ENTRY ADDRESS 

JFCB ADDRESS 

FORMAT 1 DSCB ADDRESS 

INTERNAL RETURN CODE 



8 

9 

10 

11 

12 

13 SAVE AREA ADDRESS 

1^ RETURN ADDRESS 

15 BASE REGISTER/RETURN CODE ON EXIT 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
X 

X RETURN CODE 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
MODJFCB EQU 4 RETURN CODE IF JFCB MODIFIED 

USING IFGOEXOB, RCODE 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X START OF SAMPLE PROGRAM 
X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

B AFTRIDl 

DC C'IFGOEXOB JDM1137 XSYSDATE' 
\- DC C»IFGOEXOB JDM1137 05/01/81' 

SAVE REGISTERS 

SAVE REGISTERS 
ZERO RETURN CODE 
PARAMETER LIST 
DEFAULT BUFNO 

SCREEN OUT CASES WHERE RLSE, X 
AND SQTY SHOULD NOT BE CALLED 
SET PARTIAL RELEASE 
SET SECONDARY QUANTITY 
RETURN TO CALLER 



AFTRIDl 


SAVE 


(14,12) 


+AFTRID1 


DS 


OH 


+ 


STM 


14,12,12(13) 




XR 


RINCODE, RINCODE 




USING 


OIEXL, Rl 




BAL 


RET, BUFNO 




BAL 


RET, SCREEN 




BAL 


RET, RLSE 




BAL 


RET, SQTY 


EXIT 


EQU 


X 
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X RETURN TO CALLER 

LR RCODE,RINCODE 

RETURN (14,12),RC=C15) RESTORE REGISTER 
+ L 14,12(13,0) RESTORE REGISTER 14 

+ LM 0,12,20(13) RESTORE THE REGISTERS 

+ BR 14 RETURN 

EQU X DEFAULT DCB BUFNO 

DEFINE DEFAULT VALUES 

DAMXK = NUMBER OF K (1024) OF BUFFERS FOR DASD 
TPMXK = NUMBER OF K (1024) OF BUFFERS FOR TAPE 
DAMXBNO = MAXIMUM NUMBER OF BUFFERS FOR DASD 
TPMXBNO = MAXIMUM NUMBER OF BUFFERS FOR TAPE 

NOTE THAT DAMXBNO AND TPMXBNO MUST NOT BE GREATER THAN 255 

XXXKXXXXXXXX)(XXX)(XXXXXXXKX)CXX)(X)(X)()(»CX)(XX^KXXXXXXXKXXXX)(XX)(XXX)( 



C 






BUFNO 

X 
X 
X 
X 
X 
X 

xxxxxxxxx 

DAMXK 

TPMXK 

DAMXBNO 

TPMXBNO 

INOUTBNO 



EQU 
EQU 
EQU 
EQU 
EQU 



64 
64 
32 
32 
1 



ONEK 



AFTRID2 



EQU 

B 

DC 

BCR 

L 



10 

AFTRID2 

CL8»BUFN0» 

0,RET 

RDCB,OIEXPDCB 



64K BUFFERS FOR DASD 

64K BUFFERS FOR TAPE 

32 BUFFERS MAXIMUM FOR DASD 

32 BUFFERS MAXIMUM FOR TAPE 

DCBBUFNO DEFAULT FOR SYSIN, SYSOUT, 

AND DD DUMMY 

SHIFT ARGUMENT TO MULTIPLY BY 1024 



XXX)(XXX)(X 

X 

X 

xxxxxxxxx 



BUFNO ROUTINE ID 
NOP RETURN 

PROTECTED COPY OF DCB 
USING IHADCB,RDCB 

XXXXXXXXKXXXXX)(XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

DO NOT PROCESS EXCP, BSAM, DSORG NOT PS OR PO, 
DCBBUFNO SPECIFIED 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXXX)(XXXXXXXXXXXXXXXXXXXXXXXXXXXX 



TM 

BO 

TM 

BO 

TM 

BO 

TM 

BZ 

CLI 

BNE 



DCBMACF1,DCBMRECP 

RETBUFNO 

DCBMACF1,DCBMRRD 

RETBUFNO 

DCBMACF2,DCBMRWRT 

RETBUFNO 



xxxxxxxxx 

X 
XXXXXXXKX 



xxxxxxxxx 

X 

xxxxxxxxx 



EXCP DCB? 

RETURN IF EXCP 

READ MACRO 

RETURN IF READ-NOT QSAM 

WRITE MACRO 

RETURN IF WRITE-NOT QSAM 
DCBDSRG1,DCBDSGPS+DCBDSGP0 PS OR PO 
RETBUFNO EXIT IF NOT PS OR PO 

DCBBUFNO, IS DCBBUFNO SPECIFIED 

RETBUFNO RETURN IF DCBBUFNO SPECIFIED 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxx xxxxxxxxxxxxx 
DEFAULT DCBBUFNO TO 1 FOR SYSIN, SYSOUT, TERMINAL, DUMMY 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
L RTIOT,OIEXTIOT TIOT ENTRY ADDRESS 
USING TIOENTRY,RTIOT 
L RODD,INOUTBN BUFNO DEFAULT FOR SYSIN/SYSOUT/ i 

DD DUMMY 
TM TIOELINK,TIOESSDS+TIOTTERM SYSIN/SYSOUT OR TERMINAL 
BNZ STORE BRANCH IF SYSIN OR SYSOUT OR TERMINAL 

L RJFCB,OIEXJFCB JFCB ADDRESS 
USING INFMJFCB,RJFCB 

CLC JFCBDSNM(L»NULLFILE),NULLFILE DUMMY DATA SET 
BE STORE BRANCH IF DUMMY 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
EXIT IF NO UCB ADDRESS OR BLOCK SIZE NOT POSITIVE 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 






L RUCB,OIEXUCB 

LTR RUCB,RUCB 

BZ RETBUFNO 

LH RBKSIZ,DCBBLKSI 

LTR RBKSIZ,RBKSIZ 

BNP RETBUFNO 



UCB ADDRESS 

ANY UCB? 

EXIT IF NO UCB 

DCB BLOCK SIZE 

ANY BLOCK SIZE? 

RETURN IF NO BLOCK SIZE 
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X GET TAPE OR DASD MAX TABLE 

USING UCBOB^RUCB 

TM UCBTBYT3,UCB3DACC DASD UCB? 

LA RMAX,DAMAX MAX TABLE FOR DASD 

BO CALC BRANCH IF DASD 

TM UCBTBYT3,UCB3TAPE TAPE UCB? 

LA RMAX,TPMAX MAX TABLE FOR TAPE 

BZ RETBUFNO RETURN IF NOT DASD OR TAPE 

CALC EQU K DEFAULT DCBBUFNO 

K CALCULATE DEFAULT BUFFER NUMBER 

USING MAX,RMAX 

ZERO EVEN REG 

MAXIMUM STORAGE FOR BUFFERS 

SHIFT TO MULTIPLY BY 102^ 

DIVIDE MAS BUFFER SPACE BY BKSI 

ARE THERE TOO MANY BUFFERS? 

USE CALCULATION IF NOT TOO LARGE 

USE MAXIMUM NUMBER OF BUFFERS 

DEFAULT DCBBUFNO FOR USER/COPY DCB 

PUT IN PROTECTED COPY OF DCB 

USER DCB 

MODESET USES REG 6 = REVEN 



STORE 



XR 


REVEN, REVEN 


L 


RODD,MAXBUF 


SLL 


RODD,ONEK 


DR 


REVEN, RBKSIZ 


C 


RODD,MAXBNO 


BNH 


STORE 


L 


RODD,MAXBNO 


EQU 


X 


STC 


RODD, DCBBUFNO 


L 


RDCB,OIEXUDCB 


XR 


REVEN, REVEN 



MODESET KEYADDR=0IEXUKEY,W0RKREG=6 GET IN USER KEY 



+X /x MACDATE Y-3 77277 

+x /x 

+ IC 6,0IEXUKEY 

+ SPKA 0(6) 

STC RODD, DCBBUFNO 
MODESET EXTKEY=ZERO 

+X /x MACDATE Y-3 77277 

+x /x 

+ SPKA 0(0) 
RETBUFNO EQU x 

BR RET 
INOUTBN DC A(INOUTBNO) 



aZA26071X/ 



GET KEY FROM SAVE LOCATION 

SET PSW KEY 
PUT IN USER DCB 
BACK TO KEY ZERO 



aZA26071x/ 



SET PSW KEY 
RETURN FROM BUFNO 
RETURN 

SYSIN/SYSOUT/DUMMY BUFNO DEFAULT 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx^xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X MAX TABLE FOR TAPE 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

DS OF 

DC CL8»TPMAX' TPMAX ID 

TPMAX DS OF 
TPMAXK DC A(TPMXK) MAXIMUM SIZE FOR BUFFERS IN UNITS X 

OF 102<^ 
TPMAXBNO DC A(TPMXBNO) MAXIMUM NUMBER OF BUFFERS 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X MAX TABLE FOR DASD 
X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

DS OF 

DC CLS'DAMAX' DAMAX ID 

DAMAX DS OF 
DAMAXK DC A(DAMXK) MAXIMUM SIZE FOR BUFFERS IN UNITS X 

OF 102<j 
DAMAXBNO DC A(DAMXBNO) MAXIMUM NUMBER OF BUFFERS 
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SCREEN EQU X SCREEN OUT CASES WHERE RLSE, X 

AND SQTY SHOULD NOT EXECUTE 
X)(XXXXX}(XX}(XXXXXXXXXXXXXXKXKXXXKXX)(XXXKXXXKKX)(X)()(XXX)()(XXX)(XXXXXXXXKXXX)( 
X DO NOT PROCESS IF 
K SYSIN/SYSOUT/TERMINAL 

X DD DUMMY 

X USER ASKS JFCB NOT BE RE-WRITTEN 

X SYSTEM DATA SET CSYSl.XXXM 

X NON-DASD UCB 

X NOT A FORMAT 1 DSCB 

X EXCP DCB 

X DSORG IN DCB IS NEITHER PS NOR PO 

X DSORG IN DSCB IS NEITHER PS NOR PO 

X NEITHER PUT NOR WRITE MACRO CODED IN DCB 

X OPEN FOR OTHER THAN OUTPUT OR OUTIN 

X)(XXXX)(XX}(XXXXXXXKXXXKXXXKXXXXXX)(XXXXK)()()(XXX)(XK)(X)(XXXXXX)()(XXXXXX)(XX)(XXX 



AFTRID3 



TSTMACRF 



TSTOOPT 



SCREENOK 



B 

DC 

L 

TM 

BNZ 

L 

CLC 

BE 

CLC 

BE 

TM 

BO 

L 

LTR 

BZ 

TM 

BNO 

L 



AFTRID3 

CL8' SCREEN* SCREEN ROUTINE ID 

RTIOT,OIEXTIOT TIOT ENTRY ADDRESS 

TIOELINK,TIOESSDS+TIOTTERM SYSIN/SYSOUT OR TERMINAL 

EXIT EXIT IF SYSIN OR SYSOUT OR TERMINAL 

RJFCB,OIEXJFCB JFCB ADDRESS 

JFCBDSNM(L»NULLFILE),NULLFILE DUMMY DATA SET 

EXIT EXIT IF DUMMY 

SYS1,JFCBDSNM SYSl.XXX DATA SET 

EXIT EXIT IF SYSTEM DATA SET 

JFCBTSDM,JFCNWRIT DON»T MODIFY JFCB 

EXIT IF YES 

UCB ADDRESS 

ANY UCB? 

EXIT IF NO UCB 

DASD UCB? 

EXIT IF NOT DASD 

FORMAT 1 DSCB ADDRESS 



EXIT 

RUCB.OIEXUCB 

RUCB,RUCB 

EXIT 

UCBTBYT3,UCB3DACC 

EXIT 

RDSCB^OIEXDSCB 



USING DS1FMTID,RDSCB 



CLI 

BNE 

L 

TM 

BO 

TM 

BZ 

NC 

BZ 

TM 

BZ 

EQU 

TM 

BO 

TM 

BZ 

EQU 

TM 

BO 

TM 

BNO 

EQU 

BR 



DS1FMTID,C'1» 

EXIT 

RDCB,OIEXPDCB 

DCBMACF1,DCBMRECP 

EXIT 



1 DSCB 



IS THIS A FORMAT 

EXIT IF NOT 

PROTECTED DCB ADDRESS 

EXCP DCB? 

EXIT IF EXCP 
DCBDSRG1,DCBDSGPS+DCBDSGP0 PS OR PO DCB 
EXIT EXIT IF NOT PS OR PO 

DS1DS0RG,DS1DS0RG IS DSORG SPECIFIED 
TSTMACRF TRUST DCB IF NOT SPECIFIED 

DS1DS0RG,DS1DSGPS+DS1DSGP0 IS DATA SET PS OR PO 
EXIT EXIT IF NOT PS OR PO 

X TEST MACRF IN DCB 

DCBMACF2,DCBMRPUT PUT MACRO 

TEST OPEN OPTION 

WRITE MACRO 

EXIT IF NOT WRITE 

TEST OPEN OPTION 

OPEN FOR OUTPUT 

BRANCH IF YES 

OPEN FOR OUTIN 

EXIT IF NO 



w 



TSTOOPT 

DCBMACF2,DCBMRWRT 

EXIT 

X 

OIEXOOPT,OIEXOOUT 

SCREENOK 

OIEXOOPT,OIEXOOIN 

EXIT 

RET 



RETURN TO CALL RLSE, SQTY 
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DEFINE DEFAULT VALUES 



RLSEO 



RLSEl 



RLSE EQU X SET PARTIAL RELEASE 

X 

X 
X 
X 
X 
X 
X 
X 
X 



NUMBER OF EXTENTS. IF THE DATA SET HAS THIS 

NUMBER OF EXTENTS OR MORE, THEN PARTIAL RELEASE 

WILL NOT BE ALLOWED. 

NUMBER OF EXTENTS. IF THE DATA SET HAS LESS THAN 

THIS NUMBER OF EXTENTS, PARTIAL RELEASE IS 

REQUIRED. 



xxxxxxxxx 
RLSEO 

RLSEl 



NOTE THAT RLSEO MUST NOT BE GREATER THAN RLSEl 

SETTING RLSEO TO 17 OR GREATER WILL CAUSE THIS ROUTINE TO 
NEVER PREVENT A REQUEST FOR PARTIAL RELEASE 

SETTING RLSEl TO WILL CAUSE THIS ROUTINE TO 
NEVER FORCE A REQUEST FOR PARTIAL RELEASE 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
EQU 



AFTRID4 






TSTRLSE 

RETRLSE 

EXTRLSEl 
EXTRLSEO 



EQU 

B 

DC 

BCR 

L 

TM 

BO 

CLC 

BNL 

L 

01 

LA 

B 

CLC 

BL 

NI 

LA 

EQU 

BR 

DC 

DS 

DC 

DC 



8 

8 

AFTRID4 

CL8»RLSE» 

0,RET 

RDSCB,OIEXDSCB 

DS1DS0RG,DS1DSGP0 

TSTRLSE 

DSINOEPV, EXTRLSEl 

TSTRLSE 

RJFCB,OIEXJFCB 

JFCBIND1,JFCRLSE 

RINCODE,MODJFCB 

RETRLSE 

DSINOEPV, EXTRLSEO 

RETRLSE 



SET RELEASE BIT TO ZERO IF NUMBER OF x 
EXTENTS EQUAL OR GREATER THAN THIS 
SET RELEASE BIT TO ONE IF NUMBER OF X 
EXTENTS LESS THAN THIS 

RLSE ROUTINE ID 

NOP RETURN 

FORMAT 1 DSCB ADDRESS 

IS DATA SET PARTITIONED 

DO NOT SET RELEASE FOR PARTITIONED 

FEW ENOUGH TO SET RELEASE 

BRANCH IF NOT 

SET RELEASE 

JFCB MODIFIED 

RETURN 

ENOUGH TO ZERO RELEASE 

BRANCH IF NO 



JFCBIND1,255-JFCRLSE ZERO RELEASE 



RINCODE,MODJFCB 

X 

RET 

CLS'RLSECONS* 

OH 

ALKRLSEl) 

ALICRLSEO) 



JFCB MODIFIED 

RETURN FROM RLSE 

RETURN 

RLSE CONSTANTS ID 

IF FEWER THAN THIS NUMBER OF EXTENTS, K 
PARTIAL RELEASE WILL BE SET 
IF THIS NUMBER OR MORE EXTENTS, X 
PARTIAL RELEASE WILL BE ZEROED 
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SQTY EQU X SET SECONDARY QUANTITY 

XXX)()(XXXX)(XXXXXXXXXX)()(X)(XX)(XXXXXXXX)(XX)(XX)(XX)(XXXXXXKXXKX}(XX)(»(X)(X)(XXXX)(X 



DEFINE DEFAULT VALUES 

SQTYDFL = DEFAULT SECONDARY QUANTITY. THIS QUANTITY IS 
SET IF THE SECONDARY QUANTITY IS ZERO AND THE 
PRIMARY QUANTITY IS ZERO OR ONE. IT IS USED 
IF SECONDARY QUANTITY IS ONE, AND THE NUMBER OF 
EXTENTS IS EQUAL OR GREATER TO EXTSQT. 

EXTSQT = NUMBER OF EXTENTS. IF THE DATA SET HAS THIS MANY 
EXTENTS OR MORE, THEN INCREASE SECONDARY QUANTITY. 






SQTYDFL 
EXTSQT 



AFTRID6 



TSTPRIM 



SETDFLT 



DFLTSQTY 



DFLTTRK 
STSQTY 



RETSQTY 



SQTYDFLT 
EXTSQTY 



EQU 5 

EQU 10 

B AFTRID6 

DC CL8»SQTY' 

BCR 0,RET 

L RJFCB,OIEXJFCB 

NC JFCBSQTY,JFCBSQTY 

BZ TSTPRIM 

L RDSCB,OIEXDSCB 

CLC DSINOEPV, EXTSQTY 

BL RETSQTY 

XR RODD,RODD 

ICM R0DD,7,JFCBSQTY 

LR REVEN,RODD 

SRL REVEN,! 

LTR REVEN,REVEN 

BZ SETDFLT 

AR RODD,REVEN 

B STSQTY 

EQU X 

NC JFCBPQTY,JFCBPQTY 

BZ DFLTSQTY 

XR RODD,RODD 

ICM R0DD,7,JFCBPQTY 

SRL R0DD,1 

LTR RODD,RODD 

BNZ STSQTY 

EQU X 

L RODD, SQTYDFLT 

B STSQTY 

EQU X 

L RODD, SQTYDFLT 

TM JFCBCTRI,JFCBSPAC 

BNZ STSQTY 

CLI DS1EXT1,X»01' 

BE DFLTTRK 

CLI DS1EXT1,X'81» 

BNE RETSQTY 

01 JFCBCTRI.JFCBCYL 

B STSQTY 

EQU X 

01 JFCBCTRI,JFCBTRK 

EQU X 

STCM R0DD,7,JFCBSQTY 

LA RINCODE,MODJFCB 

EQU X 

BR RET 

DS OF 

DC CLS'SQTYCONS* 

DC A(SQTYDFL) 

DC ALl(O) 

DC ALKEXTSQT) 



DEFAULT SECONDARY QUANTITY 

IF DATA SET HAS THIS MANY EXTENTS, 

THEN INCREASE SECONDARY QUANTITY 

SQTY ROUTINE ID 

NOP RETURN 

JFCB ADDRESS 

ANY SECONDARY QUANTITY 

TEST PRIMARY IF NOT 

FORMAT 1 DSCB ADDRESS 

ENOUGH TO ADD TO SECONDARY QTY 

BRANCH IF NOT 

GET SECONDARY QUANTITY 
SAVE IN REVEN 
HALVE SECONDARY QUANTITY 
IS SECONDARY ONE 
DEFAULT SECONDARY IF ONE 
150% OF SECONDARY 

SECONDARY QUANTITY IS ZERO 
IS PRIMARY QUANTITY ZERO 
DEFAULT SECONDARY 



HALVE PRIMARY 

IS PRIMARY ONE 

BRANCH IF NOT 

USE QUANTITY IN SQTYDFLT 

DEFAULT SECONDARY 

STORE SECONDARY 

PRIMARY AND SECONDARY ZERO 

GET DEFAULT SECONDARY 



TRACK EXTENT 

YES — - SET TRACKS 

CYL EXTENT 

NO — RETURN 

SET CYLINDER UNITS 

SET TRACK UNITS 
MAKE TRACK REQUEST 
STORE SECONDARY QTY 

JFCB MODIFIED 
RETURN FROM SQTY 
RETURN 

SQTY ROUTINE CONSTANTS ID 

DEFAULT SECONDARY QUANTITY 

NOTE ONE BYTE OF ZERO BEFORE EXTSQTY 

IF DATA SET HAS THIS MANY EXTENTS, X 

THEN ADD TO SECONDARY QUANTITY 



Hw„.y 



236 MVS/370 System Programming Library: Data Management 






X CONSTANTS / PATCH AREA 

NULLFILE DC C'NULLFILE » DD DUMMY DATA SET NAME 

SYSl DC C'SYS1.» START OF SYSTEM DATA SET NAMES 

DS OF 

PATCH DC C»IFGOEXOB PATCH AREA • 

DC XL50»00' 

XXXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
X 

X MAX TABLE MAPPING DSECT (MAPS TPMAX OR DAMAX) 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

MAX DSECT 

MAXBUF DS A MAXIMUM SIZE FOR BUFFERS 

MAXBNO DS A MAXIMUM NUMBER OF BUFFERS 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X DCB OPEN INSTALLATION EXIT PARAMETER LIST 

X - THE lECOIEXL MACRO IS IN SYSl.MACLIB 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

lECOIEXL 
xxxxxxxx THE MACRO EXPANSION IS NOT SHOWN 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X DCB - THE IHADCB MACRO IS IN SYSl.MACLIB 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

IHADCB DSORG=PS,DEVD=DA 
xxxxxxxx THE MACRO EXPANSION IS NOT SHOWN 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X UCB - THE lEFUCBOB MACRO IS IN SYSl.AMODGEN 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
UCB DSECT 

lEFUCBOB LIST=YES 
xxxxxxxx THE MACRO EXPANSION IS NOT SHOWN 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X TIOT - THE lEFTIOTl MACRO IS IN SYSl.AMODGEN 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
TIOT DSECT 

lEFTIOTl 
xxxxxxxx THE MACRO EXPANSION IS NOT SHOWN 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X JFCB - THE lEFJFCBN MACRO IS IN SYSl.AMODGEN 
X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
JFCB DSECT 

lEFJFCBN LIST=YES 
xxxxxxxx THE MACRO EXPANSION IS NOT SHOWN 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X 

X FORMAT 1 DSCB - THE lECSDSLl MACRO IS IN SYSl.AMODGEN 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
FIDSCB DSECT 

lECSDSLl (1) 
xxxxxxxx THE MACRO EXPANSION IS NOT SHOWN 

END 
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INDEX 



r^N 
'i^> 



ABE appendage 76-78 
abnormal-end appendage 76-78 
access method routines^ functions 

performed in I/O operations 66 
accessing VTOCs and VTOC indexes 55-64 
affecting DADSM processing 121-124 
alias name 

entry 32 

of UCS images for JES2 180 

use in retrieving catalog 
information 7-8 
allocate routine 36 
alternate track 

assigning 90> 90.1 
AM operand 

in DEBCHK macro 152 
APF (authorized program facility) 45 
appendages 

abnormal-end (ABE) 76-78 

channel-end (CHE) 76 

end-of-extent (EOE) 75 

entry points 73 

listing in SYSl .PARMLIB 78 

naming convention 78 

page fix 99 

PCI 74 

programming restrictions 73 

register usage 73 

returns 73 

start-I/0 (SIO) 73 
assigning alternate tracks 90-90.1 
associated programs 

DADSM 121 

lEHLIST 65 
ATLAS macro 

coding example 91 

houi to use 90.1 

operations performed 91 

return codes 92 

specification 90-90.1 

with track overflow option 90 
authorized appendage list 78-79 



BALANCE operand (TRKCALC macro) 161, 

164, 165 
BFALN operand (DCB macro) 84 
BFTEK operand (DCB macro) 84 
bit maps 

of allocated cylinders and tracks 42 

of allocated DSCBs 42 

of allocated VIRs 42 
block multiplexor programming notes 80 
BUFCB operand (DCB macro) 84 
buffer 

releasing 61 
buffer lists 

format 

of entries 
of header 



function 56 

how created 56 

releasing 61 
BUFL operand (DCB macro) 
BUFNO operand (DCB macro) 



84 
84 



with 
wi th 
with 
wi th 
wi th 
wi th 
wi th 
wi th 
with 
wi th 
CATALOG 
wi th 
w i th 
wi th 



14 

12 

10 

8 



19 



13 

17 

16 
22 
21 



21 

19-23 
3-10 
sets 

19 



182 
3 



56-58 
56 



CAMLST macro 

with BLDA operand 
BLD6 operand 
BLDX operand 
BLOCK operand 
CAT(BX) operand 
DLTA operand 15 
DLTX operand 
DRPX operand 
LNKX operand 
RECAT operand 
UNCAT operand 
macro 

CAT(BX) operand 19 
RECAT operand 22 
UNCAT operand 
catalog maintenance 
using CATALOG macro 
using LOCATE macro 
cataloging non-VSAM data 
coding example 20 
macro specifications 
return codes 20 
catalogs 

dummy module 
entry format 
maintai ning 

using CATALOG macro 19-23 
using LOCATE macro 4-10 
master 1 

order of search 2 
private 2 
user 1 
CCM (channel command word) 70» 100, 
See also channel program 
See also channel programs 
translation, virtual addresses to 
real addresses 70, 100-101 
CENDA operand (DCB macro) 81 
channel programs 

appendages used with 72 
execution 69-70 
initiation 69-70 
related 72 

restrictions or modification 71 
translation 100-101 
channel-end appendage 76 
CHE appendage 76 
checking the DEB 151-154 
checkpoint data set 

processed with EXCP macro 
CLOSE macro 

used with EXCP 
used with XDAP 
CODE operand (DCB 
codes 

returned from 



/f K 



101 



85 



macro 
macro 
macro) 



94 
106 
86 
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CVAF macros 221-222 
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returned Mith error message 223-227 

routing and descriptor 223 
command retry 79 
communication vector table (CVT) mapping 

macro 138 
completion codes 98» 107 

See also return codes 

folloMing use of EXCP macro 98 

following use of XDAP macro 107 
control blocks 

DCB 69^ 80 

DEB 69 

ECB 69, 97 

FCB 170 

general description 69 

lOB 69, 95-97 

PIRL 71, 157 
control password 111, 115 
conversion 

actual track address to relative 
track address 109 

of sector value for RPS devices 109 

relative track address to actual 
track address 107 
copy operation 

requirements 45 
creating protected data sets 113 
CVAF parameter list 

format 59 

function 58-59 

when created 58 
CVAF processing, of GTF trace 65 
CVAF, VTOC identification to 58 
CVAFDIR macro 

examples 197-206 

hoM to use 59 

return codes 221 

syntax 184 

uses 55-56 
CVAFDSM macro 

example 216-220 

houj to use 63 

return codes 221 

syntax 189 

uses 56 
CVAFSEQ macro 

examples 206-216 

return codes 222 

syntax 193 

uses 56 
CVAFTST macro 

example 216-220 

return codes 222 

syntax 196 

uses 55 
CVOL 

See also OS CVOL 

pointer entry 30 
CVPL 

See CVAF parameter list 
CVSTAT codes 223 

CVT (communication vector table) mapping 
macro 138 



s 



DADSM 

routines 33 

user postprocessing 121-124 

user preprocessing 121-124 
DASD (direct access storage devices) 

XDAP macro 102 
data extent block (DEB) 

use Mith EXCP macro 69 

validating 150-154 
data set 

pointer entry 27 
data set control block (DSCB) 

See DSCB 
data set security 

See password protection 
DCB fields used with EXCP macro 80-87 
DCBDIRCT field of DCB 83 
DCBFDAD field, maintaining 83 
DCBIFLGS field of DCB, permanent I/O 

error indicators 71 
DCBOFLGS field of DCB, meanings of bit 

settings 94 
DCBTRBAL field, maintaining 85 
DD operand (TRKCALC macro) 162, 164, 

165 
DDNAME operand (DCB macro) 81 
DDR (dynamic device reconfiguration), 

repositioning tape data sets 81 
DEB (data extent block) 

fields 97 

obtaining 58 

use with EXCP macro 69 

validating 150-154 
DEBCHK macro 

functions of 151-154 

specification 151-154 
defaulting buffer number, for QSAM 127 
defective track 

See assigning alternate track 
define extent command 70 
deleting a data set 

coding example 50 

macro instructions for 49 

when volume not mounted 49 
DEN operand (DCB macro) 86 
DEQ macro 

at demount facility 146 
DEVD operand (DCB macro) 84-85 
device characteristics 139-144 
device-dependent parameters in 

DCB 84-86 
DEVTAB operand (TRKCALC macro) 161, 164 
DEVTYPE macro 

for RPS devices 139 

output from 139-144 

specification 139-140 
direct access storage devices (DASD) 

XDAP macro 105 
DSCB (data set control block) 

general information 33 

missing format-1 128 

reading from VTOC by actual device 
address 

coding example 48 
macro specifications 48 
return codes 49 

reading from VTOC by data set name 
coding example 47 
macro specifications 46 
return codes 47 
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DSECT expansions 

See CVT, lEFJFCBN, lEFUCBOB, TRKCALC 
DSN order, initiating 62 
DSORG operand (DCB macro) 83, 84-85 



75 



106 

(DCB macro) 83 
75 
(DCB macro) 81 



ECB fields 

with EXCP macro 97 

with XDAP macro 106 
end-of-extent appendage 
end-of-volume 

macro 94, 
EODAD operand 
EOE appendage 
EOEA operand 
EOV macro 

and missing DSCB 128 

with EXCP macro 94 

with XDAP macro 106 
error handling 64 
error messages 

See messages, error 
error recovery 

from system or user errors 

procedures 71 
event control block 

with EXCP macro 

with XDAP macro 
examples 

of CVAFDIR macro 

of CVAFSEQ macro 

of CVAFTST and CVAFDSM 
macros 216-220 

exit module 



(ECB) 

97 

106 



64 



fields 



197-206 
206-216 



of OPEN 
EXCP macro 
control 
DCB 



228 



blocks used with 

80-87 
DEB 97 
ECB 97 
JOB 95-97 
problem programs 
real storage 98 
system control programs 

68 



68 



67 



89 



in 

in 

in 

in V=R address space 

macro specification 

macros used with 

ATLAS 90 

CLOSE 94 

EOV 94 

OPEN 87-89 
mult i volume data set requirement 89 
EXCPVR macro 98-99 
executing channel programs 
in problem programs 68 
in real storage 98 
in system control programs 
exit parameter list 
format 123 
function 121 
exit routine 

allowed processing 121 
associated parameter list 

for exit 123 

for OPEN exit 126 
contents of registers 
environment 121, 125 
list entry for RDJFCB 
module names 121 
return codes 124 
system control blocks 



67 



124 
144 

124 



used for missing DSCB 129 

when executed 121 
EXLST operand (DCB macro) 83 
expiration date 

overriding 50 
EXTEND operand (OPEN macro) 36, 



87, 146 



FCB (forms control buffer) image 

adding image to SYSl . IMAGELIB 170 
adding to SYSl .IMAGELIB 178.1 
JES2 Support 180 

retrieving from SYSl. IMAGELIB 178.4 
rules 170 

fixing data areas with EXCPVR 99 

format 

of buffer list entry 57-58 



of buffer list header 


56 




of CVAF parameter list 


59 




of exit parameter list 


123 




of OPEN exit parameter 


list 


126 


of VIER index entries 


40 




of VIERs 39 






of VTOC maps 43 






format 0-6 DSCB 33 






format-1 DSCB 






missing 129 






reading from VTOC 46 






forms control buffer (FCB) 




See FCB image 






foundation block of DCB 81 




FUNCTN operand (TRKCALC macro) 


160-165 






generation data set 
name 

use in retrieving catalog 
information 6 
generation index 

pointer entry 31 
GTF trace of CVAF processing 
See CVAF parameter list 



139 



I/O appendages 

See appendages 
I/O devices 

characteri sti cs 
ICF catalog 

master 2 

order of search 2 

user 2 
IDAL (indirect address list) 101 
IDAL (indirect data address list) 100 
lEAAPPOO, authorized appendage list 78 
lEBUPDTE program 

SYSl.PARMLIB 78-79 

use in listing appendages in 78 
lECPCNVT (relative track address to 
actual track address conversion 
routine) 107 
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release 228 
space data 228 

123 



lECPRLTV (actual track address to 
relative track address conversion 
routine) 109 
lECOSCRl (sector conversion 

routine) 109 
lEFJFCBN macro 138 
lEFUCBOB macro 137 
lEHATLAS program 91 
IF60EX0B program 

processing 228 

requesting partial 

updating secondary 
IGGPOSTO program 

associated parameter list 

contents of registers 122 

Mhen executed 122 
IGGPREOO program 

allowed processing 122-124 

associated parameter list 123 

contents of registers 122 

return codes 122 

loihen executed 122 
IGGUCSIT macro 177 
IMSK operand (DCB macro) 
index 

control entry 

link entry 26 

pointer entry 26 
INDEX and CAMLST macros 

with BLDG operand 12-13 
operand 
operand 



K operand (TRKCALC macro) 162, 164, 165 
KEYLEN operand (DCB macro) 86 



112, 
170 



83 



25 



LABEL operand (DD statement) 

password protected data set 
library character set modules 
LIST operand 

CVT macro 138 
lEFJFCBN macro 138 
lEFUCBOB macro 137 
LOCATE macro 

retrieving catalog information 
by alias name 7-8 
by data set name 3-5 
by generation name 6-7 
by relative block address 8-10 
locate record command 70 



113 



with BLDX 

with DLTX 
INDEX macro 

with BLDA 

wi th 

with 

wi th 
indexed 
indexed 
VTOCs 



10-12 
13-14 



DLTA 
DRPX 
LNKX 



operand 14-15 
operand 15-16 
operand 17-18 
operand 16-17 
access, initiating 62 
VTOCs, compared to nonindexed 
43 

indexing feature for 3211 180 
indirect address list (IDAL) 101 
indirect data address list (IDAL) 100 
initializing DASD volumes 33 
interruption handling procedures 71 
lOB chain modification 158 
lOB fields 

with EXCP macro 95-97 
with XDAP macro 106 
lOBAD operand (DCB macro) 83 
lOBSENS fields with ATLAS macro 91 



JES2 

printer support 180, 181 
JFCB (job file control block) 
147, 148, 150 

See also RDJFCB macro 
macros used with 
OPEN 147 
RDJFCB 148-150 
mapping macro 138 
modifying 127, 145-147 
processing 144-147 
job file control block (JFCB) 
See JFCB 



138, 144, 



MACRFE=(E) operand (DCB macro) 81 
macros, data management 
ATLAS 90 
CATALOG 19-23 
CLOSE 

used with EXCP macro 94 

Used with XDAP macro 106 
CVAF (VTOC access) 

syntax 184-196 

uses 55-56 
CVAFDIR 

See CVAFDIR macro 
CVAFDSM 

See CVAFDSM macro 
CVAFSEQ 

See CVAFSEQ macro 
CVAFTST 

See CVAFTST Macro 
CVPL 

See CVPL macro 
CVT 138 
DCB 80, 87 
DEBCHK 151-154 
DEVTYPE 139-144 
EOV 

and missing DSCB 129 

used with EXCP macro 94 

used with XDAP macro 106 
EXCP 89 
EXCPVR 98-99 
lEFJFCBN 138 
lEFUCBOB 137 
LOCATE 3-5 
OBTAIN 46-49 
OPEN 

and missing DSCB 129 

for JFCB 147-150 

used with EXCP macro 87-89 
PROTECT 115-120 
PURGE 154-158 
RDJFCB 144-150 
REALLOC 165-169 
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RENAME 52-55 

RESTORE 154-155, 158 

SCRATCH 49 

TRKCALC 159-165 

used Mith XDAP macro 102 

XDAP 102-105 
maintaining 115, 120 

See also PROTECT macro 

PASSWORD data set 115-120 

volume table of contents 
(VTOC) 46-55 
mapping macros 

CVT 138 

lEFJFCBN 138 

lEFUCBOB 137 

TRKCALC 165 
maps of allocated space 

for cylinders and tracks 42 

for DSCBs 43 

for VIRs 42 
master catalog 2 

order of search 3 
NAXSIZE operand (TRKCALC macro) 162, 

164 
messages 

associated codes 

descriptor codes 223 
return codes 223-227 
routing codes 223 

text and explanation 223 
MF operand 

DEBCHK macro 154 

TRKCALC macro 162-165 
MODE operand (DCB macro) 86 
modi fying 

channel program during execution 71 

lOB chain 158 

JFCB 145-147 
modifying the JFCB 127 
mult i volume data set 

processing Mith EXCP macro 88 



N 



names 

VTOC index 38 
non indexed VTOCs, compared to 

indexed 43 
nonpageable address space, V=V 70 
NOPUREAD protection-mode indicator 116 
N0i4RITE protection-mode indicator 116 



OBTAIN macro 46-47 

obtaining a sector number (RPS 

devices) 109 
OPEN exit module 125 
OPEN exit parameter list 126 
OPEN macro 

and DEQ at demount facility 146 
and missing DSCB 129 
getting control from 126 
TYPE=J 

example 88 
invoking 146 
specification 148 
used Mith EXCP macro 



dummy data set restriction 87 
label processing 87 
procedures performed 87 
volume disposition 87 
used Mith XDAP macro 103 
open processing 125 

after IFGOEXOB gets control 125 
before IFGOEXOB getting control 
from 125 
opening a VTOC, restriction on changing 

contents 149 
OPENJ (OPEN, TYPE=J) 147 
operational requirements 45 
OPTCD=Z operand (DCB macro) 82 
OS CVOL 

pointer entry 30 
OUTINX operand (OPEN macro) 83 
OUTINX operand(OPEN macro) 146 
output data set 

maintaining DCBBLKCT field 81 
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page boundary 100 
page fix 

appendage 99 

list 100 
pageable address space, V=R 68 
parameter list 

See CVAF parameter list 
partial releases requesting 127 
password 

control 115 

parameter list 

add a record 120 
delete a record 119 
li st a record 119 
replace a record 118 

protection mode indicator 116 

record 113 

secondary 115 

standard label restriction 111 
PASSUIORD data set 

characteristics 113 

creating 113 
passMord protecting data sets 111-120 
passMord protection 

counter maintenance 115 

data set concatenation 114.1 

for VTOC indexes 45 

termination 114 

volume switching 114 
PCI (program controlled interruption) 

appendage 74 
PCI operand (DCB macro) 81 
PCIA operand (DCB macro) 81 
PGFX appendage 100 
physical sequential access, 

initiating 62 
PIRL (purged I/O restore list) 

use in restoring I/O requests 71, 
157, 158 
posting completion code in ECB 

folloMing use of EXCP macro 97 

folloNing use of XDAP macro 106 
postprocessing 

See DADSM 
PREFIX operand (lEFUCBOB macro) 137 
preprocessing 

See DADSM 
printer image 
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universal character set (UCS) 170 
private catalog 2 
program controlled interruption (PCI) 

appendage 74 
programming notes 79 
programs associated Mith DFDS 

DADSM 121 
PROTECT macro 

parameter list 120 

return codes 120 

specification 116 
protecting a VTOC index 

Mith passwords 44 

with RACF 44 
protection mode indicator 116 
PRTSP operand (DCB macro) 86 
PURGE macro 

adding to macro library 155 

definition 154 

parameter list 156 » 158 

return codes 158 

specification 156 
purged I/O restore list 71 » 156 » 158 
PUREAD protection-mode indicator 116 
PMMRITE protection-mode indicator 116 



Q 



QSAIi (queued sequential access method) 
defaulting buffer number 127 



R operand (TRKCALC macro) 162» 164» 165 
RACF 

renaming a data set 52 

scratching a data set 49 

use with VTOCs and VTOC indexes 44 
RDJFCB macro 

coding example 148.1 

exit list entry for 149 

invoking DEQ at demount 146 

return codes 150 

specification 148 
reading 

data from index maps 61 

DSCBs 60, 62 

VIRs 60-61 
reading and modifying a JFCB 145-150 
reading catalog information 

using a data set name 4-5 

using a generation name 6-7 

using an alias name 7-8 
READPSUID module 112 
REALLOC macro 165 
recataloging a data set 

coding example 22 

macro specification 22 

return codes 20 
RECFM operand (DCB macro) 83 
recovering from errors 64 
recovering from permanent I/O error 

See ATLAS macro 
regi ster 

conventions for appendages 72 

usage by conversion routines 108» 
109 

usage by I/O supervisor 72 



REGSAVE operand (TrKcaLC macro) 162» 

164 
related channel programs 72 
related requests 72 
relative generation number 6 
REMOVE operand (TRKCALC macro) 161, 164 
RENAME macro 

dummy module 182 

specification 52 
renaming a data set 

coding example 53 

macro specification 52 

with password protection 55 
REPOS operand (DCB macro) 81 
requesting partial release 127 
requi rements 

for APF 45 

for copy, restore, operations 45 
Resource Access Control Facility 

See RACF 
restore chain modification 158 
RESTORE macro 

adding to macro library 155 

definition 154 

specification 158 
restore operations, requirements 45 
restoring lOBs 158 
restrictions 

when scratching, renaming, 
allocating 44 
retrieving catalog information 

See reading catalog information 
return codes 

ATLAS macro 92 

CATALOG macro 20 

considerations 2 

from CVAF macros 221-222 

lECPCNVT 109 

LOCATE macro 5-6 

OBTAIN macro 47 

RDJFCB macro 150 

to OPEN 128 

TRKCALC macro 162 

with error message 223-227 
RKDD operand (TRKCALC macro) 162, 164 
routine 

See exit routine 
RPS (rotational position sensing) 

devi ces 

used with XDAP macro 109 



SCRATCH macro 

coding example 50 

general description 49 
scratching a data set 

when volume not mounted 49 
secondary passwords 115 
secondary space data, updating of 128 
sector, address in XDAP macro 105, 109 
securing VTOC indexes 

with passwords 44 

with RACF 44 
seek 70 

serialization, VTOC 64 
SIO appendage 

description 73 

for EXCPVR 99 
SIOA operand (DCB macro) 81 
space maps 
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of allocated cylinders and tracks 

of allocated DSCBs 42 

of allocated VIRs 42 
SSCH (start subchannel) instruction 
STACK operand (DCB macro) 86 
stand-alone seek 70 
standard label restriction^ password 

data sets 111 
start subchannel (SSCH) instruction 
start-J/O appendage 

description 73 

for EXCPVR 99 
system control blocks 124 

mapping macros for CVT 
lEFJFCBN 138 
lEFUCBOB 137 
system macro instructions 
SYSl.IMAGELIB data set 

adding a UCS image to 

maintaining 170 

UCS images in 170 



42 macro specification 21 
return codes 21 
unit check with ATLAS macro 91 
unit control block (UCB) 
getting information from 

See DEVTYPE macro 
mapping macro 140 
universal character set (UCS) 

See UCS image 
updating secondary space data in 

IFGOEXOB 128 
user catalog 2 
user exit routine 
See exit routine 



137 
171 



tape volumes 

DEQ at demount facility 
testing for a VTOC index 55 
trace of CVAF processing 65 
track 

assigning alternate 90 
calculating capacity 159-165 
translation of channel programs 
by I/O supervisor 

in V=R address space 100 
in V=V address space 70 
in your own program 100 
TRKBAL operand (TRKCALC macro) 

163, 164 
TRKCALC macro 159-165 
TRKCAP operand (TRKCALC macro) 

163, 165 
TRTCH operand (DCB macro) 86 
TYPE operand 

DEBCHK macro 152 

TRKCALC macro 161, 164, 165 



160, 



160, 



UCB (unit control block) 

getting information from 
See DEVTYPE macro 

mapping macro 140 
UCB operand 

TRKCALC macro 161, 164 
UCS (universal character set) image 

adding to SYSl.IMAGELIB 171 

adding to the UCS image table 175 

for JES2 180 

verifying 178 
UCS image table 

adding aliases 175 

adding image names 175 

contents 175 

entry format 175 

modifying entries 176 

structure 175 
uncataloging a non-VSAM data set 

coding example 21 






pointer entry 
entry 24 



V=R address space, EXCP operations 

in 68 
V=V address space 70 
validating the DEB 150-154 
VCB (volume control block) 

format of 29 

use of 4 
VIER (VTOC index entry record) 

characteristics 38 

contents 39 

format 39 

function 38 

how chained together 41 

when created 40 
VIRs 

kinds 38 

length 38 
VIXM (VTOC index map) 

format 43 

function 42 
VMDS (VTOC map of DSCBs) 

format 43 

function 43 
volume control block 
volume index control 
volume label 34 
volume list 

definition 3 

use in catalog maintenance 3 
volume switching 88 
volume table of contents (VTOC) 

maintaining 

index 46, 49 
using OBTAIN macro 46-49 
using RENAME macro 52-55 
using SCRATCH macro 49 
VPSM (VTOC pack space map) 

format 43 

function 42 
VSAM catalog 

master 2 

order of search 2 

user 2 
VTOC 

See volume table of contents 
VTOC (volume table of contents) 

See also volume table of contents 

identification to CVAF 58 

maintaining 

description 33 
VTOC access macros 

CVAFDIR 

example 197-206 
return codes 221 
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syntax 184 

uses 55--56 
CVAFDSM 

example 216-220 

return codes 221 

syntax 189 

uses 56 
CVAFSEQ 

example 206-216 

return codes 222 

syntax 193 

uses 56 
CVAFTST 

example 216-220 

return codes 222 

syntax 196 

uses 55 
VTOC index 

contents 38 
hoM to list 65 
how to protect 45 
name 38 

relationship to VTOC 38 
serialization 64 
structure 38 
testing for 55 
VTOC index entry record (VIER) 

See VIERs 
VTOC index map (VIXM) 

See VIXM 
VTOC index record (VIR) 

See VIRs 
VTOC map of DSCBs (VMDS) 

See VMDS 
VTOC maps» format 43 
VTOC pack space map (VPSM) 
See VPSM 



m 



XDAP channel program 107 
XDAP macro 

control blocks used Mith 102» 106 
macros required Mith 
CLOSE 106 
EOV 106 
OPEN 102-103 
specification 104-105 
XENDA operand (DCB macro) 82 



1403 printer 
JES2 Support 



180 



180 



3203 printer 

JES2 181 

output from DEVTYPE 142 
3211 printer 

indexing feature 

JES2 Support 180 
3800 printer 

output from DEVTYPE macro 
3895 reader inscriber 

output from DEVTYPE macro 



142 
142 



U 



UAIT macro 

used Mith EXCP macro 68 
UIRITE protection mode indicator 
Mriting DSCBs 60 
Mriting VIRs 60-61 



55 



4245 printer 

default FCB image 171 

output from DEVTYPE macro 142 

UCS image table 175 
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